Programming with Class

In this project we will use a Red-Green-Blue (RGB) LED to create color sequences, morphing or stepping from one color to the next. A push-button will allow the user to switch the color sequence being displayed. RGB LEDs are used in appliances to create moods by illuminating translucent materials with varying colors. Let’s first examine the characteristics of an RGB LED.

RGB LED

RGB LEDs consist of three LEDs, one red, one green, and one blue contained in a single translucent or transparent package. Each color is controlled separately, allowing a wide gamut of colors to be created by varying the amount of electrical current flowing through each of the LEDs. The following diagram shows the RGB LED schematic and its pinout. The RGB LED portrayed is a common cathode RGB LED. Common anode RGB LEDs are also available.

RGB LED Schematic

Apart from its packaging, the RGB LED works as if it was three independent LEDs and each can be wired in a circuit the way it was done in the ‘Blink’ circuit. The following diagram shows the circuit used for this project. It contains an RGB LED as well as a push-button that will be used to switch between color sequences. Note that we are using three resistors each separately limiting current in each of the LED. If we would have put a single resistor at the common cathode junction of the LEDs, the LEDs would have still lit, but their brightness would have been impacted by other LEDs being activated or not.

The RGB LED Circuit

RGB LED Circuit

Digital I/O pin 9 is connected to the red LED; digital I/O pin 10 is connected to the green LED; and digital I/O pin 11 is connected to blue LED. All connections are made through 330Ω resistors placed between the digital I/O pin and the anode of each light emitting diode. Digital I/O pin 12 is connected to a push button that is connected to ground when depressed. A 10K pullup resistor is connected between the digital I/O pin and the 5-volt supply, ensuring a HIGH input value when the push button is not depressed.

You might have noticed the ’tilde’ character, ‘~’, associated with some of the Arduino’s digital I/O pins. These digital I/O pins are special in that not only do they support digital output as HIGH and LOW values, but they also support analog output values. Instead of being output as a constant voltage value, analog values at these pins are output as a train of on and off pulses. The ratio between on and off is determined by the analog value. This is called pulse width modulation (PWM). In the Arduino, analog output values are discrete values between 0 and 255. For an analog value of 0, the output is always off; for an analog value of 64, the output is 25% on, 75% off; for an analog value of 128, the output is 50% on and off; and for an analog value of 255, the output is always on. The brightness of each LED is proportional to the amount of on time at the digital output. The frequency of the signal at pins 9, 10, and 11 on the Arduino Uno is approximately 490Hz.

Breadboarding

The following picture depicts how to connect the different parts using a solderless breadboard, jump wires, an RGB diode, a push button, a 10K resistor and three 330Ω resistors.

Programming with Class_bb

The RGB LED Program

The purpose of the program is to display a show of colors using the RGB LED. We want the LED to change colors following a sequence of pre-selected colors. The color change can be abrupt, or gradual, depending on the sequence. Because it would be arduous to recreate the code from the code snippets in this blog, I have created a Programming with Class repository on the Git Website. Simply click on the link, then on the “Clone or Download” button to download a zipped version of the files and copy them in a folder named “ProgrammingWithClass” on your computer. You can then load the “ProgrammingWithClass.ino” sketch in the Arduino Integrated Development Environment (IDE).

The program in this project can be fetched from the  Programming with Class repository on the Git Web site.

The Main Sketch

As usual, the Arduino sketch file starts with a comment stating the purpose of the program, the author and copyright notice. The program is licensed under the standard MIT license.

Next, we include two files: “rgbLed.h” and “rgbColor.h“. These files declare the rgbLed and rgbColor classes. We will cover the content of these files, what classes are, and how to program them later in this post. For now, let us simply accept that these classes exist and that we can create variables with them which I will describe shortly.

/*
Main ProgrammingWithClass sketch
Program that outputs sequences of colors to an RGB LED. The
sequence shown can be selected by a push button. This sketch
demonstrates the use of classes. It is associated with the
Programming with Class blog post on https://lagacemichel.com
MIT License
Copyright (c) 2018, Michel Lagace
*/
#include "rgbLed.h"
#include "rgbColor.h"

We have already seen an example of a class: the String class. The String class comes with the Arduino system. It allows programmers to easily work with character sequences. We already have used String classes as part of the Morse Code Generator project. One characteristic of variables created with classes is that they encapsulate, that is hide, the data that they contain. A String variable certainly contains a sequence of characters and possibly a length value, or maybe it is implemented using a null-terminated character sequence. We do not know, unless we actually look at the code implementing the String class and truly, we do not care as long as we can operate on a String. Another characteristic of variables created from classes is that we can call functions, called methods when associated to classes, directly acting upon the variable. As an example from the Morse Code Generator project, we use the length() method associated with a String as follows:

String text = "abcd";
int length = text.length();

In the code above, we create a variable text of type String, the name of the class, and initialize it with the character string “abcd”. We then create an integer variable called length and initialize it with the length, the number of characters, contained in the text variable using the length() method. The method is called by appending the variable name with a period (‘.‘) then the name of the method followed by parenthesis. Methods behave very similarly to functions and there could be parameters within the parenthesis following the method name if required. Notice the strength of variables created from classes as they behave almost like data types.

Variables created from classes are also called ‘objects‘. Along with a set of rules, design patterns, and best practices, objects are at the root of Object-Oriented Programming. Arduino software is written in C++, an object-oriented programming language that also allows C-language constructs. In the next section we will see how to use the rgbColor and rgbLed objects. Later in the blog, we will see the details of the implementation of these classes.

The rgbColor and rgbLed Classes

The rgbColor class allows programmers to create color objects based on the red, green and blue emissive color triad. Users can create a rgbColor object using the three colors or simply by declaring a rgbColor variable without stating values. rgbColor object declaration has the following forms: rgbColor color(float red, float green, float blue) or rgbColor color. Following are examples of rgbColor object declarations.

rgbColor red(1.0, 0.0, 0.0);
rgbColor black;

In the first case, a red object is created by setting the red component to 1.0 and the green and blue components to 0.0. Color components are set to floating point values between 0.0 and 1.0, from completely off to completely on. A rgbColor object can also be created without any component, in which case all components are set to 0.0, corresponding to black. rgbColor objects can also be created from other rgbColor objects, or by assigning a rgbColor object to another.

rgbColor darkRed(0.25, 0.0, 0.0);
rgbColor anotherRed(red);
anotherRed = darkRed;

rgbColor object anotherRed is created as a copy of object red, then assigned the value of just created rgbColor object darkRed. rgbColor also sports three methods to obtain the values, between 0.0 and 1.0, of each color component making up the color stored in a rgbColor object. The following depicts these methods.

float r = darkRed.red();
float g = darkRed.green();
float b = darkRed.blue();

Methods, as shown above, are function names following an object name, separated by a period (‘.‘). The rgbColor class supports one more method, the gradate() method.

rgbColor blue(0.0,0.0,1.0);
rgbColor green(0.0,1.0,0.0);
rgbColor cyan;
cyan.gradate(blue,green,0.5);

The gradate() method assigns to the rgbColor object a color between the first and second color specified, scaled according to the third function parameter, the gradient. The gradient specifies the amount mixed from each color according to the formula

Color = (1.0 – Gradient)•Color1 + Gradient•Color2

A value of 0.0 makes the resulting color equal to the first color, C1; a value of 1.0 makes the resulting color equal to the second color, C2; a value between 0.0 and 1.0 makes the resulting color a combination of both colors according to the gradient specified.

The program uses objects from a second class, the rgbLed class. Each rgbLed object represents an external RGB LED and the actual Arduino pins associated with it. There is no default value possible and three PWM capable digital output pins must be specified to create a rgbLed object.

rgbLed device(8,9,10);

In this line of code, a rgbLed variable is created for an RGB LED whose red LED is connected to the Arduino’s digital pin 8, whose green LED is connected to digital pin 9 and whose blue LED is connected to digital pin 10. The rgbLed class supports only one method, the set() method which assigns a rgbColor object to the rgbLed object.

rgbColor orange(1.0,0.2,0.0);
rgbLed device(8,9,10);
device.set(orange);

In this code snippet, we create the orange rgbColor object, the rgbLed device object representing the external RGB LED attached to the Arduino pins 8, 9 and 10, and we set the external RGB LED to light up orange.

Next in the Main Sketch

Back to the program, we define the RGB LED digital output pins, then the push-button digital input pin. We then set constants to cycle through colors in 10 seconds in 1000 steps, 10 milliseconds per step. We then initialize the global variable that keeps track of the color cycle step.

Next, we use a construct that was never used before, the enumerated type. Enumerated types declare sequences of value names making up an enumeration of things. Enumerated types are themselves named, allowing variables to be created using the enumerated type name. Enumerated types are declared using the enum reserved word followed by the enumerated type name, followed by an enumeration of names separated by commas and enclosed in curly brackets. The whole construct is followed by a semicolon.

In the code below, an enumerated type called colorScheme has the following enumerated value names: nothing, wheel, rainbow, all, and white. In Arduino’s memory, enumerated type value names are encoded as integers starting at 0. Hence, setting a colorScheme variable to rainbow will assign it the value 2 and setting a colorScheme variable to white will assign it the value 4. We added an extra value at the end of the enumeration, numberOfSchemes. It gets assigned the value 5, which is the number of actual color schemes in the list. Following the enumeration is a variable declaration making scheme a colorScheme variable initialized with nothing.

// RGB LED pins
#define REDPIN   9
#define GREENPIN 10
#define BLUEPIN  11

// Pushbutton pin
#define PUSHBUTTON 8

// Constants used to control timings
const int colorCycle = 1000;
const float cycleTime = 10.0;
const int stepTime = cycleTime/colorCycle*1000;
// Color step counter
static int colorStep = 0;

// Color scheme names
enum colorScheme {nothing,
                  wheel,
                  rainbow,
                  all,
                  white,
                  numberOfSchemes
};
static colorScheme scheme = nothing;

//Push Button current value
bool pushButton = HIGH;

// Global LED object
static rgbLed led(REDPIN,GREENPIN,BLUEPIN);

// Array of color sequences made of rgbColor objects
static const rgbColor wheelColors[] = 
  {redColor,yellowColor,greenColor,cyanColor,blueColor,magentaColor};
static const rgbColor rainbowColors[] = 
  {redColor,orangeColor,yellowColor,greenColor,blueColor,
   purpleColor,blackColor};
static const rgbColor allColors[] =
  {redColor,greenColor,blueColor,yellowColor,cyanColor,magentaColor,
   orangeColor,purpleColor,whiteColor,blackColor};

Following the enumerated type variable is a Boolean variable holding the current input value of the push-button. It is initialized to HIGH. As in the Toggle Push-Button blog post, we are interested in the moment the button is pushed as it goes from HIGH to LOW. After, we declare the variable led representing the external RGB LED connected to three Arduino digital output pins that support pulse width modulation. Then, we declare constant arrays of rgbColor values, three in all. Each array corresponds to a color sequence we want displayed at the RGB LED. The color values such as redColor and cyanColor are constants that are declared within the rgbColor class header file. The following RGB color constants have been declared:

  • redColor
  • greenColor
  • blueColor
  • yellowColor
  • cyanColor
  • magentaColor
  • orangeColor
  • purpleColor
  • whiteColor
  • blackColor

Computing the Color of the RGB LED

The main Arduino sketch contains two functions: glideThrough() and stepThrough(). Both functions take two parameters, the color array containing the sequence of colors to glide or step through, and an integer containing the number of colors in the array.

In these functions, each color gradient, or solid color depending on the function, is displayed for the same amount of time, depending on the number of colors in the array. The gradientSpan variable contains the number of steps out of the total number of steps to spend between two colors.

For the glideThrough() function, we select the index of the colors between which we will gradually morph. The first color is selected according to the current step in the color cycle. The second color is the next color in the array. If we have reached the end of the color array, the second color is set to the first color in the array, starting a new color cycle. This is done using the modulo operator ‘%‘, that provides the remainder of the division with the number of values in the array. The gradient value is set to a value between 0.0 and 1.0 corresponding to the step position between the two colors we want to blend, or glide through. Finally, we compute the color blend using the gradate() method of a rgbColor object and then assign the rgbColor object to the rgbLed led object using the set() method.

For the stepThrough() function, we select the color to display according to the current step in the color cycle. We create a rgbColor object initialized with the appropriate color in the color array and assign the rgbColor object to the rgbLed led object using the set() method.

// Glide through colors
void glideThrough(rgbColor colorArray[],int arraySize) {
  // Initialize color gradients
  float gradientSpan = (float)colorCycle/(float)arraySize;

  // Compute color array indices and gradient between colors
  int gradateFrom = colorStep/gradientSpan;
  int gradateTo = (gradateFrom + 1)%arraySize;
  float gradient = colorStep/gradientSpan - (float)gradateFrom;

  // Gradate between the two colors
  rgbColor color;
  color.gradate(colorArray[gradateFrom],colorArray[gradateTo],gradient);
  led.set(color);
}

// Step through colors
void stepThrough(rgbColor colorArray[],int arraySize) {
  // Initialize color gradients
  float gradientSpan = (float)colorCycle/(float)arraySize;

  // Compute color array indeces and gradient between colors
  int colorIndex = colorStep/gradientSpan;

  // Set the color according to time
  rgbColor color(colorArray[colorIndex]);
  led.set(color);
}

Main Sketch Setup

In the setup() function of the main sketch, we setup the push-button digital input pin. The RGB LED digital output pins are setup as part of the rgbLed object construction that we will see later in the post.

// Setup push button pin
void setup() {
  // Setup pin modes
  pinMode(PUSHBUTTON,INPUT);
}

Main Sketch Loop

The first thing we do in the sketch’s loop() function is to display colors according to the selected scheme. This is done through a series of if else statements, selecting the appropriate scheme. If scheme is nothing or white, the RGB LED is set to black or white respectively. If scheme is wheel or rainbow, the RGB LED is set to gradually morph from one color to the next of the wheelColors and rainbowColors respectively. If scheme is all, the RGB LED steps through all available color values. Anything else is a programming error and would set the RGB LED to a solid red color.

Next, we check if the push-button has changed state. If so, and if the old value is HIGH, making the transition from HIGH to LOW, we select the next color scheme. If scheme goes beyond the number of schemes, it is reset to nothing. Upon change of the color scheme, the color step is reset to zero. Upon a change of state of the push-button, the old push-button value is set to the new one.

Finally, we wait the computed step duration before starting the next step. This delay also serves as a de-bounce delay. We then increment the color step and cycle back to zero if the we have reached the end of the color cycle.

// Main loop. Repeatedly through color sequences
void loop() {
  // Output color according to selected scheme
  if (scheme == nothing) {
    led.set(blackColor);
  }
  else if (scheme == wheel) {
    glideThrough(wheelColors,sizeof(wheelColors)/sizeof(rgbColor));
  }
  else if (scheme == rainbow) {
    glideThrough(rainbowColors,sizeof(rainbowColors)/sizeof(rgbColor));
  }
  else if (scheme == all) {
    stepThrough(allColors,sizeof(allColors)/sizeof(rgbColor));
  }
  else if (scheme == white) {
    led.set(whiteColor);
  }
  else { // Program error, this should never happen
    led.set(redColor);
  }
  // Detect if button is going from HIGH to LOW. If so, select next
  // color scheme
  if (digitalRead(PUSHBUTTON) != pushButton) {
    if (pushButton) {
      colorScheme = colorScheme + 1;
      if (colorScheme >= numberOfSchemes) {
        colorScheme = nothing;
      }
      colorStep = 0; 
    }
    pushButton = !pushButton;
  }

  // Wait a bit, then proceed to next color step
  delay(stepTime);
  colorStep++;
  if (colorStep >= colorCycle) {
    colorStep = 0;
  }
}

Object-Oriented Programming

Classes are at the heart of object-oriented programming. They allow programmers to combine data structures, attributes, with code constructs, methods. It allows information collections to be treated as data types. This what we will see in the next sections. We will describe two classes, rgbColor and rgbLed. In C++, classes are declared in header files and code is developed in class implementation files. The header file, ending with the .h file type, contains the interface to objects created from the class while the implementation file, ending with the .cpp file type, contain the code of the different methods associated with objects of the class.

In order to act as data types, classes need to define a few methods that are called whenever an object is created, deleted, or assigned to. If not provided, C++ creates these methods by default. These methods are

  • the default constructor
  • the destructor
  • the copy constructor
  • the assignment operator

Classes that systematically declare these methods are said to follow the orthodox canonical class form. The default constructor is called whenever a new object is created from the class without any parameter or initial values. Its syntax is simply the name of the class followed by parenthesis.

className();

The destructor is called whenever an object goes out of scope, such as when a function exits. It allows the system to release memory and to relinquish links to other objects. Its syntax is the class name preceded by the tilde (~) symbol and followed by parenthesis.

~className();

The copy constructor allows an object of a class to be constructed from another object of the same class. Its syntax is the name of the class followed by a reference to a constant object of the same class within the method’s parenthesis. The & after the class name signifies that a reference to the object is passed to the function instead of a copy. The const keyword signifies that the object referenced cannot be modified.

className(const className&);

The assignment operator allows an object to be assigned from another one of the same class. Its syntax is a reference to a class name followed by operator = followed by a reference to a constant object of the same class within the method’s parenthesis. Here again, the ampersand signifies that we are passing and returning a reference to an object instead of a copy of the object. This is more efficient, especially if objects contain a lot of information.

className& operator = (const className&);

Within the class declaration, methods and attributes that are available outside of the class’ code are declared public. Within the class declaration, anything following a public: declaration is visible and usable by all code outside and within the class. Within the class declaration, anything following a private: declaration is only visible to code within the class. Generally speaking, attributes, that is variables within the class, are in a private section of the class declaration. Sometimes, we do not want the default constructor, copy constructor, or assignment operator to be automatically generated by the compiler and we do not want to provide them to class users. This is achieved by putting them in the private section of the class.

The following sections contain header files and implementation files for the rgbColor and rgbLed classes. Consult a C++ primer to better understand classes in C++.

rgbColor.h Header File

The rgbColor header file defines the rgbColor class. C++ and .ino files that want to use objects of the rgbColor class must include this file using the ‘#include‘ statement. The header file contains the class definition that declares a default constructor, a destructor. a copy constructor and an assignment operator within its public section. A constructor from red, green, and blue floating point components is also declared. Three accessor methods, red(), green() and blue() are declared to return the floating point value of each color component. Finally, the gradate() method explained earlier in the post is declared.

Then follows a private section containing the color components declared as bytes. Although colors are set and accessed as floating-point values between 0.0 and 1.0, they are stored as integer values between 0 and 255 in order to save memory space.

Finally, a set of constant rgbColor objects are created that contain the red, green, blue, yellow, cyan, magenta, orange, purple, white and black colors.

/*
rgbColor class (header)
Class rgbColor stores a color and operates on it.
MIT License
Copyright (c) 2018, Michel Lagace
*/
#if !defined(RGBCOLOR_HEADER)
#define RGBCOLOR_HEADER
#include "arduino.h"

// Class rgbColor
class rgbColor {
  public:
    // Orthodox Cannonical Form
    rgbColor(); // Default Constructor
    ~rgbColor(); // Destructor
    rgbColor(const rgbColor&); // Copy Constructor
    rgbColor& operator = (const rgbColor&); // Assignment operator
    // Other constructors 
    rgbColor(float r,float g,float b);
    // Object accessors (set/get)
    const float red() const;
    const float green() const;
    const float blue() const;
    // Object methods
    void gradate(const rgbColor c1, const rgbColor c2, float g);
  private:
    // Color components
    byte redComponent;
    byte greenComponent;
    byte blueComponent;
};

// Global constant colors 
static const rgbColor redColor(1.0,0.0,0.0);
static const rgbColor greenColor(0.0,1.0,0.0);
static const rgbColor blueColor(0.0,0.0,1.0);
static const rgbColor yellowColor(1.0,0.6,0.0);
static const rgbColor cyanColor(0.0,1.0,1.0);
static const rgbColor magentaColor(1.0,0.0,0.5);
static const rgbColor orangeColor(1.0,0.1,0.0);
static const rgbColor purpleColor(0.2,0.0,0.2);
static const rgbColor whiteColor(1.0,1.0,1.0);
static const rgbColor blackColor(0.0,0.0,0.0);
#endif

rbgColor.cpp Implementation File

The rgbColor implementation file contains the implementation of all methods, including constructors, destructor, assignment operator, declared in the header file. All method names within the file are prefixed with the class name followed by two colons. In the case of the rgbColor class, all its methods are prefixed with rgbColor::. We will describe each method in turn.

The default constructor rgbColor::rgbColor() initializes all color components to zero. The destructor rgbColor::~rgbColor() does nothing. The copy constructor rgbColor::rgbColor(const rgbColor& color) copies each color component from the source to the current object. The assignment operator rgbColor& rgbColor::operator =(const rgbColor& color) first checks if the source being copied from is the object itself. If not, it copies each color component from the source to the current object. The assignment operator also returns a reference to the rgbColor object.

The constructor rgbColor::rgbColor(float r,float g, float b) transforms each color component from a 0.0 to 1.0 value to a 0 to 255 value. It also clamps values between 0 and 255. The method rgbColor::gradate(rgbColor c1, rgbColor c2, float g) computes the color value between c1 and c2 at the gradient g specified. The gradient is a floating-point value between 0.0 and 1.0. The resulting color is computed according to the following formula.

Color = (1.0 – Gradient)•Color1 + Gradient•Color2

Finally, the rgbColor::redComponent(), rgbColor::greenComponent(), and rgbColor::blueComponent() methods return the value of each component as a floating point value between 0.0 and 1.0.

/*
rgbColor class (implementation)
Class rgbColor stores a color and operates on it
MIT License
Copyright (c) 2018, Michel Lagace
*/

#include "rgbColor.h"

// Default constructor. Set to black.
rgbColor::rgbColor() {
  redComponent = 0;
  greenComponent = 0;
  blueComponent = 0;
}

// Destructor. Does nothing.
rgbColor::~rgbColor() {
}

// Copy constructor. Constructs a color from another.
rgbColor::rgbColor(const rgbColor& color) {
  redComponent = color.redComponent;
  greenComponent = color.greenComponent;
  blueComponent = color.blueComponent;
}

// Assignment operator. Assigns a color to another.
rgbColor& rgbColor::operator =(const rgbColor& color) {
  if (&color != this) {
    redComponent = color.redComponent;
    greenComponent = color.greenComponent;
    blueComponent = color.blueComponent;
  }
  return *this;
}

// Constructor with initializers. Initialize the color with
// the specified red, green, and blue value.
rgbColor::rgbColor(float r, float g, float b) {
  // Limit red component between 0 and 255
  if (r <= 0.0) {     redComponent = 0;   }   else if (r >= 1.0) {
    redComponent = 255;
  }
  else {
    redComponent = (byte)(r*255.0);
  }
  // Limit green component between 0 and 255
  if (g <= 0.0) {     greenComponent = 0;   }   else if (g >= 1.0) {
    greenComponent = 255;
  }
  else {
    greenComponent = (byte)(g*255.0);
  }
  // Limit blue component between 0 and 255
  if (b <= 0.0) {     blueComponent = 0;   }   else if (b >= 1.0) {
    blueComponent = 255;
  }
  else {
    blueComponent = (byte)(b*255.0);
  }
}

// Set color value as a gradient between two values.
// Color1 and color2 are the values between which the new value
// will be set as a gradient between the two values. Gradient
// is a value between 0 and 1.
void rgbColor::gradate(const rgbColor startColor,
                       const rgbColor endColor,
                       float gradient) {
  redComponent = startColor.redComponent +
    (endColor.redComponent - startColor.redComponent)*gradient;
  greenComponent = startColor.greenComponent +
    (endColor.greenComponent - startColor.greenComponent)*gradient;
  blueComponent = startColor.blueComponent +
    (endColor.blueComponent - startColor.blueComponent)*gradient;
}

// Red, green and blue accessors. Return values.

const float rgbColor::red() const {
  return redComponent/255.0;
}

const float rgbColor::green() const {
  return greenComponent/255.0;
}

const float rgbColor::blue() const {
  return blueComponent/255.0;
}

rgbLed.h Header File

The rgbLed header file defines the rgbLed class. C++ and .ino files that want to use objects of the rgbLed class must include this file using the ‘#include‘ statement. The header file contains the class definition that declares a destructor within its public section. A constructor from red, green, and blue digital output pin assignment is also declared. The set() method allows users to assign a color to a rgbLed object. The default constructor, copy constructor and assignment operator are declared in the private section and cannot be used for rgbLed objects. Then follows a private section containing the pin numbers corresponding to the red, green and blue LEDs declared as integers.

/*
rgbLed class (header)
Class rgbLed represents an external rgbLed
MIT License
Copyright (c) 2018, Michel Lagace
*/

#if !defined(RGBLED_HEADER)
#define RGBLED_HEADER

#include "rgbColor.h"

//Class rgbLed
class rgbLed {
  public:
    // Orthodox cannonical form
    ~rgbLed(); // Destructor
    // Other constructors
    rgbLed(int,int,int);
    // Color assignment of RDG LED
    void set(const rgbColor);
  private:
    // Unusable and hidden orthodox cannonical form
    rgbLed();  // Default constructor
    rgbLed(const rgbLed&); // Copy constructor
    rgbLed& operator = (const rgbLed&); // Assignment operator
  private:
    // RGB LED associated Arduino pins
    int redPin;
    int greenPin;
    int bluePin;
};

#endif

rgbLed.cpp Implementation File

The rgbLed implementation file contains the implementation of all methods declared in the public section rgbLed header file. All method names within the file are prefixed with the class name followed by two colons. In the case of the rgbLed class, all its methods are prefixed with rgbLed::.

The destructor rgbLed::~rgbLed() does nothing. The rgbLed::rgbLed(int redPin, int greenPin, int bluePin) constructor sets the specified pins as output and sets their digital value to LOW, extinguishing all LEDs. The rgbLed::set(rgbColor color) method writes an analog value between 0 and 255 corresponding to each color value to the RGB LED pins.

/*
rgbLed class (implementation)
Class rgbLed represents an external rgbLed
MIT License
Copyright (c) 2018, Michel Lagace
*/

#include "Arduino.h"
#include "rgbLed.h"

const int ANALOGMAX = 255;       // Maximum analog output value

// Destructor. Does nothing.
rgbLed::~rgbLed() {
}

// Constructor with initializers. Initalizes the LED with
// the specified red, green, and blue pins.
rgbLed::rgbLed(int r, int g, int b) {
  redPin = r;
  greenPin = g;
  bluePin = b;
  pinMode(redPin,OUTPUT);
  pinMode(greenPin,OUTPUT);
  pinMode(bluePin,OUTPUT);
  digitalWrite(redPin,LOW);
  digitalWrite(greenPin,LOW);
  digitalWrite(bluePin,LOW);
}

void rgbLed::set(rgbColor color) {
  // Output color to RGB LED
  analogWrite(redPin,color.red()*ANALOGMAX);
  analogWrite(greenPin,color.green()*ANALOGMAX);
  analogWrite(bluePin,color.blue()*ANALOGMAX);
}

A Better Transistor Switch Circuit

In the previous post, we have seen how to drive a relay using an NPN bipolar junction transistor. The circuit allowed a digital input signal to activate and deactivate a relay coil. As seen previously, the following graph depicts what is happening to the relay coil voltage drop with respect to the input voltage from an Arduino digital output pin.

Simple Transistor Relay Switch Plot

Looking at the bottom horizontal band, the relay electrical characteristics guarantee that the relay is off for input values between 0 volts and 1 volt; and looking at the top horizontal band, the relay electrical characteristics guarantee that the relay activates when the input voltage is above approximately 2.75 volts. What if we wanted the relay to remain off until the input voltage to be at least 2 volts, and the relay to be on when the input voltage is at most 3 volts?

Biasing the Base of the Transistor

There is a way in our circuit for base-emitter voltage drop not to be equal to Vin when the transistor is in cut-off mode. Remember that the transistor requires a forward voltage drop of 0.7 volts, for silicon-based bipolar junction transistors, between the base and emitter before current can flow through the base and thus the collector. While current is not flowing through the base or base resistor, the voltage at the base is the same as the voltage at the input. How can we make the voltage at the input of the base resistor higher than the voltage at the base? By using a voltage divider.

The Voltage Divider

The voltage divider is a simple circuit where two resistors in series divide the voltage amongst them. According to Kirchhoff’s voltage law, as seen in the Blink post, the sum of the electromotive forces, as provided by batteries, in any closed loop is equivalent to the sum of the voltage drops in that loop. Thus, in the following circuit,

voltage divider

The sum of voltage drops across R1 and R2 is equal to VDC. The current IDC in the circuit is, according to Ohm’s law, I = V/R or

IDC = VR1/R1 = VR2/R2
IDC = (VR1 + VR2) / (R1 + R2)
IDC = VDC / (R1 + R2)

The voltage across R2 is

VR2 = IDC•R2
VR2 = VDC•R2 / (R1 + R2)

If VDC is 2 volts and we want VR2 to be 0.7 volts then

0.7 V = 2 V•R2 / (R1 + R2)
0.35•R1 + 0.35•R2 = R2
0.35•R1 = 0.65•R2

Lets apply this to the complete switch circuit from the previous post and add a resistor, RBias between the base of the transistor and ground.

Transistor Switch with Bias

In this circuit, as previously computed, in order for the Vin value of 2 volts to produce a voltage of 0.7 volts across the base and emitter of the transistor, RBase and RBias must satisfy the following equation

0.35•RBase = 0.65•RBias
RBase = 0.65•RBias / 0.35

When the base-emitter voltage reaches 0.7 volts, current starts flowing into the base of the transistor and the base-emitter voltage remains 0.7 volts. According to Kirchhoff’s current law the sum of currents flowing into the junction of the base resistor, the bias resistor and the base node is equal to the sum of currents flowing out of that junction. The current flowing into the junction through the base resistor is

I = (Vin – 0.7 V) / RBase

The current flowing out of the junction through the bias resistor and the transistor’s base is

I = 0.7 V / RBias + IBase

Hence,

IBase = (Vin – 0.7V) / RBase – 0.7 V / RBias

Now, assuming a resistive relay coil load of 70 Ω, a power supply of 5 V and a transistor hFE of 250, the base current at start of transistor saturation is

IBase = 5 V / (70 Ω•250) ≅ 0.286 mA

As stated earlier, we want Vin to be 3 volts at saturation and using the base current equation, we get

0.286 mA = (3 V – 0.7V) / RBase – 0.7V / RBias

Replacing RBase with the voltage divider circuit equation computed for the resistor values at cutoff we get

0.286 mA = (3V – 0.7V) / (0.35 RBias/0.65) – 0.7V / RBias
RBias = 1795 Ω ≅ 1.8K

Replacing RBias in the cutoff voltage divider equation we get

RBase = 0.65•RBias / 0.35 = 3333 Ω ≅ 3.3K

Resulting New Circuit

The following diagram depicts the transistor relay switch circuit with a voltage divider at the base of the transistor switch. The values of the resistors are 3.3K for the base resistor and 1.8K for the bias resistor.

Connected Biased Transistor Relay Switch

The following graph depicts what is now happening to the relay coil voltage with respect to the input voltage from an Arduino digital output pin when the voltage divider is used at the base of the transistor.

Biased Transistor Relay Switch Plot

Notice how we get a cleaner and sharper voltage transfer between the input signal and the voltage at the relay coil. This new circuit ensures that weaker input digital signals can be used to operate the transistor relay switch.

Breadboarding

The following picture depicts how to connect the different parts using a solderless breadboard, jumper wires, a transistor, a diode, a relay, a push button, a 10K resistor, a 1.8K resistor and a 3.3K resistor. Connections to the household appliance are not shown.

A better Transistor Switch Circuit_bb

WARNING:

The project in this post involves household mains high-voltages. Use caution whenever dealing with high-voltage wiring, including following directions carefully and following general safety practices. Safe assembly and operation of this project is the user’s responsibility. If unsure or if local laws prohibit the assembly of high-voltage circuits, get the help of a professional electrician. Do not make changes to the system while the device is plugged in.

Transistor Driven Relay Switch

Up to now, we have seen how to input digital (on and off) information from a simple electromechanical device, the push-button, and how to output a digital signal to an LED. What if, instead of an LED, we wanted to turn on and off an actual household light. There are obvious electrical differences between LEDs and household lights. LEDs only require a few milliamperes of current and work very well in low voltage circuits such as the 5 volts provided by an Arduino board. A household light, on the other hand, requires mains electricity, between 110 and 240 volts depending on your location, and higher currents, between 200 milliamperes and one ampere. A microcontroller digital output cannot directly provide enough power to light a household light.

Relays are electromechanical devices, like the push-button. Instead of requiring a mechanical force to push on the device to close or open a circuit, it relies on an electromagnet to pull on a metal plate to close the circuit with metal contacts with which the plate makes a connection. We can thus close or open a higher voltage and higher current circuit by applying a voltage to the relays electro-magnet that pulls on a metal plate to close the circuit.

It the following sections, we will have a look at a few electronic and electromechanical devices: the relay, the diode, and the transistor.

Relays

Relays have two distinct, electrically independent parts. The first part is an electromagnet, a coil of insulated copper wire wound around a metal bracket, the yoke, that becomes magnetic when a current is applied to it. The other part is a spring-loaded metallic plate or armature resting on metal contacts. When a current is applied to the electromagnet, enough force is applied to the armature for it to disconnect from its resting contacts and make an electrical connection with another set of metallic contacts on which the armature rests for as long as there is electrical current in the electromagnet. When current stops flowing in the electromagnet, the spring attached to the metallic armature forces it back to its initial resting position, making an electrical connection between the metallic plate and the resting contacts.

Relay Parts

Relays come in a variety of sizes and ratings. Ratings are used to select a relay to be used for specific applications. Automotive relays, for instance have rated coil voltages of 12 volts. Relays intended to be used in household appliances have rated coil voltages of 120 or 240 volts. Following is a list of relay coil ratings supplied by manufacturers.

  • Rated Coil Voltage – the voltage that is intended to be applied to the coil to operate the relay.
  • Pull-In Voltage – the minimum voltage that can be applied to the coil for it to operate the relay.
  • Drop-Out Voltage – the voltage below which an activated relay will return to its resting state.
  • Maximum Continuous Voltage – the maximum voltage to be applied to the coil above which permanent damage occurs.
  • Nominal Operating Current – current flowing through the coil when the rated coil voltage is applied.
  • Nominal Operating Power – the power used by the coil when the rated coil voltage is applied.
  • Coil Resistance – the continuous current resistance of the coil in ohms.

Within circuit diagrams, the electromechanical relay is represented as a coil and contacts as in the following diagram depicting normally open and normally closed relay forms.

Relays

Relay contacts have ratings stating the relay’s intended use. Following are relay contact ratings supplied by manufacturers.

  • Contact Forms – the contact mechanism and the number of contacts in the contact circuit.
    • Form A – normally open (N.O.) contact.
    • Form B – normally closed (N.C.) contact.
    • Form C – changeover contacts.
    • MBB – Make-Before-Break contacts where normally open contacts close before normally closed contacts break open.
  • Rated Switching Power – the intended use value in watts of the load that can switched by the contacts.
  • Maximum Switching Voltage – maximum voltage that can safely be switched by the contacts.
  • Maximum Switching Current – maximum current that can safely be switched by the contacts.
  • Maximum Switching Power – the maximum power to be switched by contacts above which damage may occur.

For the current project, we will use a 5 volts miniature relay, the FRS10C-S12, to turn on and off a household lamp. This relay has the following coil characteristics:

  • Rated coil voltage of 5 volts.
  • Pull-in voltage of 3.75 volts.
  • Pull-out voltage of 0.5 volts.
  • Nominal operating current of 70 mA.
  • Coil resistance of 70 Ω.

It has the following contact characteristics:

  • Form C contact form, changeover contacts.
  • Contact rating of 12A at 125VAC (1,500W) or 10A at 250VAC (2,500 W)

The chosen relay’s coil operates on 5 volts, suitable for an Arduino provided power supply, but requires 70 mA to operate, which is much larger than the rated output current of 20 mA that each Arduino digital output can provide. We need a device that can boost the current provided by the digital output pin to drive the relay coil. That device is a transistor.

Transistors

Transistors are semiconductor devices used to amplify or switch electronic signals and electrical power. There are many types of transistors, but the most common is the bipolar junction transistor (BJT). There are two types of bipolar junction transistors, the NPN and PNP types, describing the material and configuration used to build the device. For the current project and tutorial, we will use an NPN transistor. There are several configurations that transistor circuits may use. In order to explain how the transistor operates, I will be using the common-emitter configuration, that is a transistor circuit with its emitter directly connected to ground. Consider the following circuit.

NPN Transistor

The transistor, labelled Q1, is at the center of the diagram. It is represented by a circle with a vertical bar from which three branches are attached. The diagonal branch at the top is called the collector. It is connected to a resistor, RLoad, representing the device to be switched on or off. The branch to the left of the transistor symbol, perpendicular to the bar is called the base. It is connected to a resistor, RBase, that controls the current flowing into the base. Finally, the diagonal branch with the arrow pointing outward is the emitter. If the arrow had been pointing towards the bar inside the symbol, we would have a PNP transistor. In this circuit, the emitter is connected to ground. The principle of operation of the transistor is that a small current flowing from the base to the emitter of the transistor will allow a larger current flowing from the collector to the emitter, thus amplifying the base current.

Transistors, like other electronic devices, have specifications telling us about the electrical limitations of the devices as well as information about their capabilities. In the circuit that we will build later on, we will use a BC337-40 NPN Bipolar Junction Transistor. I have found the following information from the product data sheet provided at SparkFun.

  • Maximum Collector-Base Voltage |VCES| – 50 V, the maximum voltage drop between the collector and the base.
  • Maximum Collector-Emitter Voltage |VCEO| – 45 V, the maximum voltage drop between the collector and the emitter.
  • Maximum Emitter-Base Voltage |VEBO| – 5 V, the maximum reverse voltage drop between the emitter and the base.
  • Maximum Collector Current |IC| – 800 mA, the maximum amount of current that can flow through the collector.
  • Power Dissipation |PD| – 650 mW, the power dissipation of the device.
  • Forward Current Transfer Ratio |hFE|, minimum – 250, the minimum amount of current amplification between the base current and the collector current.
transistor cbe

Here is a picture of the BC337-40 transistor above. It comes in a TO-92 package, a small plastic half cylinder with a flat face on which the transistor markings are written and three metal pins sticking out at the bottom of the package. When the transistor’s flat face is facing the reader, the collector pin is at the left side of the transistor, the base is the center pin, and the emitter pin is at the right side of the transistor.

Transistor Operation

One characteristic that all silicon transistors have is the forward bias voltage required between the base and the emitter for the transistor to work. Remember that in a previous post titled the Blink circuit, we saw that the LED had a constant voltage drop across its anode and cathode. Similarly, transistor based on silicon have a voltage drop of approximately 0.7 volts between their base and emitter when in operation. Below that voltage, no current flows through the base nor the collector. When the base-emitter voltage (VBE) of the transistor is increased to 0.7 volts, current starts flowing through the base and through the collector. The base-emitter voltage remains at 0.7 volts while current flows through the base. The amount of current flowing through the collector (IC) is proportional to the current flowing through the base (IB) times the Forward Current Transfer Ratio (hFE) of the transistor.

IC = IB = 0,   if VBE < 0.7 V
IC = hFE•IB,  if VBE ≥ 0.7 V

Common Emitter

Looking at the circuit above, an increase of voltage at Vin will get VBE to increase until it reaches 0.7 volts. Since no current flows through RBase, the voltage drop across the resistor is 0 volts and VBE = Vin. While VBE is less than 0.7 volts, the transistor is said to be in cut-off mode. As Vin is increased beyond 0.7 volts, current starts flowing through the base and collector, making the transistor enter the normal amplification operation mode. Following Ohm’s law, I = V / R, and since the current going through the base is the same as the current through the base resistor

IB = (Vin – 0.7 V) / RBase

In the normal amplification operation mode, the voltage across the load resistance RLoad, VLoad, is proportional to the collector current, itself proportional to the base current.

VLoad = IC•RLoad
VLoad = IB•hFE•RLoad
VLoad = ((Vin – 0.7 V) / RBase)•hFE•RLoad

As the voltage across RLoad increases, the voltage across the transistor’s collector and emitter pins decreases until VCE reaches 0 volts. At that point, any increase in the base current has no effect on the collector current and the transistor is said to have reached saturation. At saturation, we have:

IC = VCC / RLoad

The load to be turned on and off is the relay described earlier with a coil resistance of 70 Ω for a supply of 5 volts. At saturation, the collector current is 5 V / 70 Ω or approximately 71 mA. When connecting the base of transistor to an Arduino digital output pin through the base resistor, Vin is 0 volts when a LOW is output to the digital output and 5 volts when a HIGH is output to the digital output. Another way of stating this could be that any input voltage below 2.5 volts is LOW and anything above 2.5 volts is HIGH. Hence, we want a saturated transistor when the input voltage is above 2.5 volts. Assuming a transistor hFE of 250, we can use the equation to compute VLoad from Vin to compute RBase

VLoad = ((Vin – 0.7 V)•hFE•RLoad / RBase)
RBase = (Vin – 0.7 V)•hFE•RLoad /  VLoad
RBase = (2.5 V – 0.7 V) •250•70 Ω / 5 V
RBase =  6,300 Ω

The closest resistor value in my kit is 10K, which should be close enough. Lets now build the circuit. First, we replace the resistive load by the relay coil and we replace the base resistor with a 10 K resistor. The Vin input is replaced with the Arduino’s digital output pin 11.

Transistor Relay Switch

Note the addition of a new device between the terminals of the relay’s coil. Its symbol resembles that of the LED that we saw in previous projects, but without the outward arrows. The device is called a diode. As for the LED, current flows in the direction of the arrow, from anode to cathode. The diode in this circuit serves as a protection for the transistor. The coil of the relay stores energy as it is turned on and it releases that energy when it is turned off as a voltage pulse that can damage the transistor by exceeding its maximum rated collector voltage. The diode acts as a short, preventing the spike from damaging the transistor. In normal operation, the diode does not let current through.

Let’s have a look at a graph plotting the voltage drop across the relay’s coil as a function of the voltage at the Arduino’s digital output pin.

Simple Transistor Relay Switch Plot

On the plot, we see that the voltage applied to the load is 0 volts for as long as the input voltage is below 0.7 volts. Then, as input voltage increases, voltage at the relay coil increases until the input voltage reaches approximately 3.5 volts, at which point the voltage drop across the relay’s coil reaches 5 volts and the transistor enters saturation.

The vertical blue bands represent the guaranteed LOW and HIGH voltage values output by the Arduino’s digital output pin. The top horizontal blue band represents the voltage zone in which the relay is on and the bottom blue horizontal band represents the voltage zone in which the relay is guaranteed to be off. In the diagram, we note that the relay is off for all guaranteed values for Arduino’s LOW output and that it is on for all guaranteed values for Arduino’s HIGH output.

The maximum base current is 5 V / 10 K, or 0.5 mA, a totally acceptable value for the Arduino’s digital output capability. The next step, is to connect a household device to the relay.

The Final Circuit

The relay contacts are exactly like wall switch contacts and can be used to turn on or off household appliances. In the final circuit, the relay contacts are inserted as a switch in one of the wires of a lamp’s power cord. A push-button is used to turn the lamp on and off using the Arduino program described in the LED Toggle with a Push-Button Switch post.

Connected Transistor Relay Switch

Breadboarding

The following picture depicts how to connect the different parts using a solderless breadboard, jumper wires, a transistor, a diode, a relay, a push button and two 10K resistors. Connections to the household appliance are not shown.

Transistor Driven Relay Switch_bb

The Program

The following Arduino program completes the post. Cut and paste the code in your Arduino IDE and download it to complete the project. It will toggle the lamp on and off at each press of the pus button.

/* Household Light Toggle
   Uses a transistor connected to pin LED_BUILTIN as
   a switch for a relay that toggles on and off a
   household lamp at the press of a button.
   This sketch was written by Michel Lagacé, 2018-10-08
   This code is in the public domain. */

// Button value will be read from pin 12
#define INPORT 12
#define OUTPORT 11

// Time to wait in milliseconds to consider switch debounced
#define DEBOUNCE_DELAY 10

// LED state kept across loops
static bool outputValue;

// Setup the board.
void setup() {
    pinMode(INPORT, INPUT);
    pinMode(OUTPORT,OUTPUT);
    outputValue = LOW;
    digitalWrite(OUTPORT,outputValue);
}

// Wait for an edge and return state
bool waitForEdge() {
    bool startValue = digitalRead(INPORT);
    bool newValue = startValue;
    while (newValue == startValue) {
        newValue = digitalRead(INPORT);
    }
    delay(DEBOUNCE_DELAY);
    return newValue;
}

// Repeat forever
void loop() {
    // Wait for a rising or falling edge
    bool value = waitForEdge();

    // Toggle output on dropping edge (input is LOW when button is pressed)
    if (!value) {
        outputValue = !outputValue;
        digitalWrite(OUTPORT, outputValue);
    }
}

WARNING:

The project in this post involves household mains high-voltages. Use caution whenever dealing with high-voltage wiring, including following directions carefully and following general safety practices. Safe assembly and operation of this project is the user’s responsibility. If unsure or if local laws prohibit the assembly of high-voltage circuits, get the help of a professional electrician. Do not make changes to the system while the device is plugged in.

LED Toggle with a Push-Button Switch

This new circuit is an evolution of the LED blinker circuit and program. Instead of using a delay to alternately turn the LED on and off, we are going to use a push-button to signal the system to toggle an LED on or off.

Hooking Up a Push-Button Switch to the Arduino

A push-button switch is a very simple electro-mechanical device that has a spring-loaded contact, keeping the circuit open, that is unconnected, until the button is pressed, forcing a metal piece to bridge internal contacts thus closing the electrical circuit and allowing current to flow through. The circuit re-opens as the pressure on the push button is released, preventing current from flowing.

Floating Inputs

Let’s connect normally open push-buttons as in the following diagram.

Push Button

While the button is pushed, the circuit works. S2 is connected to the power supply, providing a HIGH value to the input pin; S1 is connected to ground, providing a LOW value to the input pin. When the push-button is not depressed, what is the value at the input pin? It is undefined, neither HIGH or LOW, or possibly fluctuating between the two values as the unconnected input acts like an antenna, picking up signals from the surrounding electromagnetic noise. This situation is known as floating inputs and must be corrected.

There is a solution. As shown in the following diagram, we can connect a resistor to ground, called a pull-down resistor, for the switch connected to the power supply; or connect a resistor to the power supply, called a pull-up resistor, for the switch connected to the ground. These resistors will ensure that the value at the input pin is always in a known state.

Pull-up Pull-down
Pull-up and pull-down resistors

The value of R can be very high as the Arduino’s digital pin input impedance, that is its opposition to current when a voltage is applied, is very high.  My current SparkFun kit has 10K resistors that will do the job. Setting R to 10K will limit the current to 0.5mA (remember, V = RI, I = V/R) when the switch is closed, allowing current to flow. The Arduino offers an input pin mode that programmatically attaches a 20K pull-up resistor to the input pin, limiting the current to 0.25 mA when the switch is closed. This mode, of course, only works if the push-button is connected to ground.

The LED Toggle Circuit

The circuit that we will use is shown in the diagram below. The push-button switch is connected to the Arduino‘s input pin 12 and to a 10K pull-up resistor. The LED‘s anode is connected to digital pin 13 and its cathode, to ground through a 330Ω current limiting resistor, exactly as was done in the LED blinker circuit.

LED Toggle
LED Toggle’s complete circuit

One thing that must be said about push-buttons is that because they are electromechanical devices, the electrical contact is not instantaneous and electrical noise is produced every time the switch is closed or opened. This is caused by the way spring-loaded metal pieces bounce as they make contact with metal connectors closing the circuit within the switch. This bouncing of metal against metal makes the contact close and open repeatedly for a few milliseconds. This happens as the switch closes and as it opens. There are debouncing electronic circuits that can be used to counteract this effect. In this post, we will only use a software solution explained as part of the program below.

Breadboarding

The following picture depicts how to connect the different parts using a solderless breadboard, jumper wires, an LED, a push button, a 10K resistor and a 330Ω resistor.

LED Toggle_bb

The LED Toggle Program

You can copy the following code directly in the Arduino IDE.

Following the usual header, you will find definitions for the INPORT, input port value, and DEBOUNCE_DELAY, the time in milliseconds to allow the switch to stabilize after it changes state when it closes or opens. Finally, the Boolean value outputValue holds the on and off LED values, HIGH for turned on and LOW for turned off.

First, we prepare the board circuitry in the setup() function. The pin mode for pin INPORT is set to INPUT, which will allow us to read the switch value. Digital I/O pins on the Arduino board can be set to either output a value or input a value, not both at the same time. The circuit described previously uses a 10K pull-up resistor. We could have specified the pin to be INPUT_PULLUP instead, which would have programmatically installed a 20K pull-up resistor at the digital input pin. The pin mode for pin LED_BUILTIN is set to OUTPUT, allowing the program to output HIGH or LOW values to the LED circuitry. Within setup(), the outputValue is set to LOW and sent to the output pin, thus extinguishing the LED.

/* Light Toggle
   Uses an LED connected to pin LED_BUILTIN as a light
   source toggled on and off at the press of a button.
   This sketch was written by Michel Lagacé, 2018-09-16
   This code is in the public domain. */

// Button value will be read from pin 12
#define INPORT 12

// Time to wait in milliseconds to consider switch debounced
#define DEBOUNCE_DELAY 10

// LED state kept across loops
static bool outputValue;

// Setup the board.
void setup() {
    pinMode(INPORT, INPUT);
    pinMode(LED_BUILTIN,OUTPUT);
    outputValue = LOW;
    digitalWrite(LED_BUILTIN,outputValue);
}

// Wait for an edge and return state
bool waitForEdge() {
    bool startValue = digitalRead(INPORT);
    bool newValue = startValue;
    while (newValue == startValue) {
        newValue = digitalRead(INPORT);
    }
    delay(DEBOUNCE_DELAY);
    return newValue;
}

// Repeat forever
void loop() {
    // Wait for a rising or falling edge
    bool value = waitForEdge();

    // Toggle output on dropping edge (input is LOW when button is pressed)
    if (!value) {
        outputValue = !outputValue;
        digitalWrite(LED_BUILTIN, outputValue);
    }
}

The waitForEdge() function waits until the switch value changes from HIGH to LOW or LOW to HIGH and then returns the new switch value. The function first reads the current switch value using the digitalRead() built-in function. It then sets the newValue variable to be the same as the value just read and loops, using a while loop, until the value of the switch becomes different from the first value read. The program then waits for DEBOUNCE_DELAY milliseconds to let the switch settle. I have measured the duration of the bounce noise produced by a micro push-button switch and found that it was never more than approximately 4 milliseconds. I believe that it is therefore safe to let the switch settle for twice that amount of time. Since the switch cannot be depressed manually for more than 50 times per second, it is also safe to assume that a 10 millisecond wait will not prevent normal operation of the switch. The limitation that a 10 millisecond delay imposes is that we will not be allowed to close and open the switch within a 20 millisecond lapse of time, having to wait 10 milliseconds when the switch is closed and another 10 milliseconds when the switch is open. The waitForEdge() function returns the last switch value read.

The while loop works similarly to the for loop seen in the Morse code generator. It executes the code contained between the curly braces until the specified condition is not met, or false. Unlike the for loop, the while loop lacks initializer and post-processing statements. it has the following structure:

    while (condition) {
        // Execute the code within the curly braces
    }

Finally, the main loop() function repeatedly waits for a switch value change through a call to the waitForEdge() function. If the returned value is LOW, that is the push-button has been depressed making the!value condition true, the LED outputValue is inverted, or toggled, and then output to digital pin LED_BUILTIN.

What Next?

This circuit shows how one can read a digital value using the digitalRead() function, how switch noise can be removed with a debouncing delay, and how the while loop control structure works. You can experiment with the circuit and program to see first what happens if you remove the pull-up resistor and move your hand around the circuit. The LED will turn off or on unexpectedly without you having touched the switch. You can also try to touch the open digital input attached to the switch with your finger. The LED will start flickering as your body acts as an antenna and picks up the 50 or 60 Hz electromagnetic signals surrounding us. As another experiment, comment out the delay() line within the waitForEdge() function and depress the switch repeatedly. At some point, the LED will remain as it was, without toggling, or will briefly flicker, quickly turning on and off.

Morse Code Generator

Lets Beef-Up the ‘Blink’ Program

A blinking circuit may be useful as a signal to warn others of dangerous situations or to draw people’s attention. Another use for a blinking light is to communicate with someone over a distance. The following program makes use of the blinking light circuit to implement a Morse code generator.

Around 1837, the American Samuel F. B. Morse invented an early version of what was to become Morse code. Morse code is a method of transmitting information as a series of on-off tones, lights, or clicks. Basically, letters, numbers, and punctuation marks are translated to a variable length collection of dots and dashes, of shorter and longer bursts of sound or light. The duration of the dot, the short burst, is the unit of time by which all other elements of Morse code are defined. A dash, the long burst, is a signal whose duration is three times that of the dot. The time between dots and dashes within an encoded character is one unit of time. the time between characters is three units of time and the time between words is seven units of time.

International Morse code is thus composed of five elements:

  • short mark, dot or ‘dit’: one time unit long
  • longer mark, dash or ‘dah’: three time units long
  • gap between the dots and dashes within a character: one time unit long
  • gap between letters of a word: three time units long
  • gap between words: seven time units long

Following, is the international Morse code equivalent, in dot (.) and dash (-) notation for each alphabetical and numerical character:

315px-International_Morse_Code.svg

For instance, if we are to show the character sequence “PARIS” in Morse code, we can represent it in text as “.–.  .-  .-.  ..  …” and if we want to represent it as a series of on and off signals, arbitrarily represented by an equal sign “=” and an underscore “_” respectively, each one time unit in duration and we follow the rules stated above, we get the following signal:

___=_===_===_=___=_===___=_===_=___=_=___=_=_=___

The following program, written in “C” for the Arduino, converts a character string of alphabetical characters into a series of short and long blinking LED signals corresponding to their morse code equivalent. You can reconstruct the program in the Arduino IDE (Integrated Development Environment) by copying the code from this post and pasting it in sequence, as it appears in this text, in the text editing pane of the IDE.

The Program Header

The program header, a few paragraphs down, contains a comment describing the nature and purpose of the program as well as a copyright notice. I am the author of the code and I have put it in the public domain. Comments are character sequences ignored by the program interpreter or compiler. Comments can be formatted as any text between a slash-asterisk, ‘/*‘, and asterisk-slash, ‘*/‘, character sequences. This is the original way to enter comments in the ‘C’ language. Text enclosed between these two-character sequences can span several lines and are ignored. Comments can also be entered after a double-slash, ‘//‘, character sequence. All text after the double-slash character sequence, until the end of line, is considered a comment and is ignored by the program interpreter or compiler.

We define the digital output PORT as LED_BUILTIN, the digital output port corresponding to the Arduino’s built-in LED. The UNIT_TIME value corresponds to the time in milliseconds of the ‘on’ duration of the dot. The #define statement allows programmers to associate text to a name. When the program is compiled, the text replaces the name whenever it appears in the program. At compile time, PORT is replaced by the Arduino LED_BUILTIN  constant and UNIT_TIME is replaced by the integer value 100. Note that LED_BUILTIN is also a definition and it gets substituted by the appropriate integer value depending on the target Arduino board.

The characters String variable and codedCharacters String array variable work in tandem as the list of supported characters and their corresponding Morse code equivalent. The Morse code equivalent is encoded as a character string containing a series of period (‘.‘) and dashes (‘‘) representing the short and long bursts of Morse code. Each string in the codedCharacters array corresponds to the character at the same index in the characters string variable.

/* Morse Code Generator
   Blink an LED connected to pin LED_BUILTIN to display morse
   code corresponding to text entered. Repeats forever.
   This sketch was written by Michel Lagacé, 2018-09-02
   This code is in the public domain */

// Output port to display morse code
#define PORT LED_BUILTIN

// unit time length of the morse encoding
#define UNIT_TIME 100

// Characters to be encoded
static String characters = "abcdefghijklmnopqrstuvwxyz";

// Morse code sequences for each character
static String codedCharacters[] = { 
    ".-", "-...", "-.-.", "-..", ".", "..-.", "--.", "....",
    "..", ".---", "-.-", ".-..", "--", "-.", "---", ".--.",
    "--.-", ".-.", "...", "-", "..-", "...-", ".--", "-..-",
    "-.--", "--.." };

In ‘C++‘, an array is a collection of elements accessible through the use of an index. A String is a specialized array for collections of characters. Thus, each character in a String and each element of an array can be accessed through the use of an index. An index is an integer value enclosed in square brackets ([ ]) right after the variable name. The first character of a string or element in an array has index 0. The second character or element has index 1 and each successive character or element’s index is one more than the preceding index.

In the code above, character ‘c’ is at index 2 in the characters String. The corresponding Morse code sequence, “-.-.”, is a String at index 2 in the codeCharacters String array. The characters variable is declared as static meaning that the variable’s memory is allocated once at the start of the program and remains for the duration of the program. Non-static variables in functions are allocated in memory only for the duration of the execution of the function, then released back to the pool of memory a program can use. This is very useful for very large programs as only the necessary memory is used at any time. The characters String is initialized with the character string “abcdefghijklmnopqrstuvwxyz”. codedCharacters is also declared as a static String, but the variable name is followed by square brackets. These square brackets indicate that the variable is an array. The size of the array is set to the number of elements it is initialized with. In this case, 26 elements. If an uninitialized array is to be created, the size can be specified as a value within the square brackets.

Digital Output Setup

The setup of the digital output to blink an LED is identical to the setup in the ‘BLINK’ circuit demonstration. We set the pin mode to OUTPUT.

// Setup the board. Digital port LED_BUILTIN in output mode
void setup() {
    pinMode(PORT, OUTPUT);
}

Outputting Dots and Dashes

Code can be, and should be, segregated into functions that provide specific well-defined functionality to a program. Functions, also called subroutines, are sequences of code that can be called by name. In the ‘C’ language, functions must be defined before they are used and thus must appear in the code before any code that uses them. The simplest functions have the following structure:

void functionName() {
    // Sequence of code the function performs when called
}

The void reserved word specifies that the function does not return any value. The we have the function name, followed by a sequence of code enclosed in curly braces, ‘{‘ and ‘}‘. Elsewhere in the program, if we want to call up the sequence of code contained i the function, we simply use the function name, followed by parentheses and a semicolon:

    functionName();

In the Morse code program, we first define two functions, one to output a dot, put the LED on for one time unit, then off for one time unit; and the other to output a dash, put the LED on for three time units, then off for one time unit. In the following code, you will find both functions. They are very similar to the code found in the original ‘BLINK’ program: lights on, lights off.

/* Function to output a dot: one unit on, one unit off */
void outputDot() {
    digitalWrite(PORT,HIGH);
    delay(UNIT_TIME);
    digitalWrite(PORT,LOW);
    delay(UNIT_TIME);
}

/* Function to output a dash: three units on, one unit off */
void outputDash() {
    digitalWrite(PORT,HIGH);
    delay(UNIT_TIME*3);
    digitalWrite(PORT,LOW);
    delay(UNIT_TIME);
}

Encoding a Character in Morse Code

Next, we have a function that outputs a character as a series of dots and dashes. Before having a look at this function, let’s go through a few concepts that will help people unfamiliar with ‘C++’ understand the code better.

‘C++’ Classes

In ‘C++’, functions can be attached to data structures called classes. I will not delve on classes, but suffices to say that these functions are called methods. The String data type is actually a class called String. Variables created with a class are usually called objects. In the case of the String class, because it is used as a data type, I will still call them variables. The String class has several methods associated with it. in the following function, we use the indexOf() and length() methods. The indexOf() method returns the index of the first occurrence of the character passed as an argument in the String. The length() method returns the number of characters in the String. To use a method associated to a variable, use the variable name followed by a period, followed by the method name, parentheses, and any parameter required by the method. It is like calling a function, but preceded by the variable name. Thus, to get the index of the position of letter ‘f’ within the characters String and initialize the index variable with it, use the following code:

    int index = characters.indexOf('f');

index will be initialized with the value 5, the index of the letter ‘f’ in the String characters.

The outputCharacter function introduces us to two fundamental programming structures. The for-loop, and the if-then-else structures.

if-then-else Control Structure

The if-then-else control structure allows a program to conditionally execute a portion of a program. It has the following structure:

    if (condition) {
        // Code to execute if condition is true
    }
    else if (other condition) {
        // Code to execute if other condition is true
    }
    else {
        // Code to execute if all preceding conditions are false
    }

Only the first if block is mandatory; the else if and else blocks are optional. The execution flow is as follows: if the condition specified within parenthesis after the first if is true, then the code within the curly braces following the if statement is executed; if the condition within the first if statement is false then the condition in the else if statement is checked; if the condition in the else if statement is true, then the code within the curly braces following the else if statement is executed; if the condition in the else if statement is false, then the code contained within the curly braces after the else statement is executed. There can be several else if statements, each testing a different condition.

for-loop Control Structure

The for-loop control structure allows the program to iterate through code several times until a condition is met. It has the following structure:

    for (initialization; condition; post-processing {
        // Code to execute until condition is met
    }

where initialization is a statement executed just before entering the loop; condition is a test performed at the beginning of the loop, if true, code within the for-loop curly braces is executed, if false, execution continues after the loop; and post-processing, is a statement executed after each iteration through the code within the curly brackets. For instance, in the following for-loop control structure:

    for (int i = 0; i < 10; i++) {
        // Code executed 10 times
    }

Variable i is initialized to 0 before entering the loop; i is tested if smaller than 10, since it is, the code within the curly braces is executed and i is available for use within this code; after the code within the curly braces is executed, the variable i is incremented by 1. A second iteration of the loop then starts and i is tested if smaller than 10. The loop continues until the condition i < 10 is false. The loop executes 10 times with values of i from 0 to 9.

outputCharacter Function

Looking at the function header, we find that it is similar to the previous functions, but has a parameter within the parentheses: char c. This defines a single character parameter to the function. Parameters allows the calling program to pass values to the function. In this case, the character to be output as Morse code. Within the outputCharacter function, variable index is set to the index of character c in the characters String. If the character is found, that is if index is greater or equal to 0, then we output the Morse code. To do so, we get the Morse code associated with the character using index to retrieve the Morse code string from codedCharacters. We then iterate through each character of the Morse code and output a dash, if the character is a hyphen or a dot otherwise using the outputDash() and outputDot() functions respectively. At the end of the character output, we wait an extra 2 units of time, totaling the 3 units of time required at the end of a Morse code character. The wait totals 3 units of time since we already introduced a single unit of time delay at the end of the dash or dot.

/* Function to output a single character */
void outputCharacter(char c) {

    // Find index of character to encode
    int index = characters.indexOf(c);
 
    // Ignore unencodable characters
    if (index >= 0) {

        // Encode Morse code and output it
        String code = codedCharacters[index];
        for (int i = 0; i < code.length(); i++) {
            if (code[i] == '-') {
                outputDash();
            }
            else { // if not '-', must be '.'
                outputDot();
            }
        }

        // wait 3 units at the end of the letter
        // (2 units assuming previous dot or dash)
        delay(UNIT_TIME*2);
    }
}

Encoding Text into Morse Code

The sentence function’s purpose is to output text as Morse code. It accepts the single String parameter: text. First, the function gets the length of the text and stores it in the len variable. It then iterates through the whole text String using i as the index in a for-loop structure from 0 until len – 1. It gets the character indexed by i and turns it to lowercase using the tolower() built-in function. If the character is not a space, it is output using outputCharacter(). If the character is a space, we wait an extra 4 units of time, totaling the 7 units of time required at the end of a word. The wait amounts to 7 units of time since we already added 3 units of time at the end of the previous Morse code character output.

// Function to encode a whole string
void sentence (String text) {
    // Compute length of character string
    int len = text.length();

    // Output each character in turn
    for (int i = 0; i < len; i++) {

        // Only lower case characters are encoded
        char c = tolower(text[i]);
        if (c != ' ') {
            outputCharacter(c);
        }
 
        // Spaces are encoded as 7 units,
        // (4 units assuming a previous character)
        else {
            delay(UNIT_TIME*4);
        }
    }
}

The Main Loop

Finally, this is the main loop(). This code is repeated over and over. It outputs the text “Mikes Electro Shack” in Morse code, then waits 28 units of time corresponding to 4 spaces between words. The delay is actually specified as 25 units of time since the last character output already added a 3 units of time delay. You can of course replace the text by any text you see fit.

void loop() {
    sentence("Mikes Electro Shack");
    delay(UNIT_TIME*25); // Wait 4 spaces at the end
}

What Next?

Through the implementation of this fairly simple program, we have seen two extremely important control structures, the if-then-else control structure and the for-loop control structure. We have seen that the String data type is implemented as a class and that there are methods associated with it. We also have seen a few String methods such as indexOf() and length().

This program can be put to use to learn Morse code, which is required to get one’s ham radio (amateur radio) license. Complete the list of characters to include numbers and punctuation marks and their equivalent Morse code to complete the experience.

Arduino’s Blink

The very first project everybody makes in any Arduino starter kit is the blinking LED project, “Blink.” In this post, we will have a look at the theory behind this simple circuit and program.

The Circuit

This circuit is very simple and contains only two components. An LED’s anode is connected to a current limiting resistor, which is connected to the Arduino’s digital output pin 13. The LED’s cathode is connected to the Arduino’s ground as in the following circuit:

Blink Circuit

When the Arduino’s digital output pin is set to HIGH or 5 volts, current flows through the resistor and LED making the LED emit light. When the Arduino’s digital output pin is set to LOW or 0 volt, current stops flowing and the LED does not emit light.

Each component will be described later in the post. The value of the resistor may vary from one kit to another. I will explain how to compute its value later in the post.

Breadboarding

The following picture depicts how to connect the different parts using a solderless breadboard, jumper wires, an LED and a 330Ω resistor.

Arduinos Blink_bb

The Program

We start with the simple blinker program found in most if not all Arduino kits. If it is not included in your kit, you can always download a copy of Blink on the Arduino site. The following is an excerpt from the actual listing, some comments have been removed for clarity.

/* Blink: turns an LED on for one second, then off for one second,
   repeatedly.
   This example code is in the public domain.
   http://www.arduino.cc/en/Tutorial/Blink  */
 
 // the setup function runs once when you press reset
 void setup() {
   // initialize digital pin LED_BUILTIN as an output.
   pinMode(LED_BUILTIN, OUTPUT);
 }
 
 // the loop function runs over and over again forever
 void loop() {
   // turn the LED on by making the voltage HIGH, wait a second
   digitalWrite(LED_BUILTIN, HIGH);
   delay(1000);
   // turn the LED off by making the voltage LOW, wait a second
   digitalWrite(LED_BUILTIN, LOW);
   delay(1000);
 }

The language used within the Arduino IDE (Integrated Development Environment) is actual C++. The major difference is that the Arduino system does not call a main( ) function like it does under normal Windows or Linux console applications. instead, the system expect the programmer to define two ‘C’ functions:

void setup();

and

void loop();

The setup( ) function (or method) is called once the first time the program is downloaded, once after the Arduino board reset button has been depressed, or once the Arduino board has been powered up. The loop( ) function is called repeatedly and indefinitely after setup( ) has been called once.

The Arduino system also comes with a set of predefined function libraries. In our first example, two functions are used to access the digital output pin to make the LED blink. The first function’s signature (this is how we call a function’s description) is

void pinMode ( int pin, int mode );

Where pin is an integer specifying the digital pin to be setup and mode is an integer specifying the mode this pin will be used in. In the program above, the pin number used is LED_BUILTIN which corresponds to the pin number connected to the built-in Arduino board LED, pin 13 on the Arduino UNO. The mode can have one of three values: INPUT, OUTPUT, or INPUT_PULLUP, all constant values that can be used as the digital I/O pin mode. In the program, we use OUTPUT, allowing us to use the pin as a digital output. The pinMode( ) function is used as part of the setup( ) function body to prepare the LED_BUILTIN digital I/O pin to be outputted to.

The second function signature is

void digitalWrite ( int pin, int value );

Where pin is an integer specifying the digital pin we are outputting to, while value is an integer whose value can be 0 or 1, LOW or HIGH. digitalWrite( ) can only be used if the pin mode was previously set to OUTPUT.

The last function signature used within our simple piece of code is

void delay( int value )

where value is an integer specifying the amount of time in milliseconds (thousandths of a second) the program is to wait and do nothing. In the program above it waits twice for a full second each time, leaving the LED on for a full second then turning it off for a full second.

Components

Two electronic components are used within this circuit, a resistor and an LED. We will describe each in turn in the following paragraphs

Resistors

Resistors are electronic devices that restrict current flow according to Ohm’s law. Ohm’s law states that the current through a conductor between two points is directly proportional to the voltage across the two points. In mathematical terms, Ohm’s law can be restated

I = V / R

Where I is the current in amperes (A), V is the voltage across the conductor in volts (V) and R is the resistance of the conductor in ohms (Ω). Hence, a 330Ω resistor with 5V across its leads will let a current flow of 5V / 330Ω, 0.01515A, or 15.15mA.

Resistors
Two 1/4 watt carbon film resistors

Resistors restrict current by dissipating energy in the form of heat. This is an important factor as resistors have to be selected not only in terms of their resistance, but also for their capacity to dissipate heat, or power rating. The energy dissipated per second by a resistor, the electrical power, is expressed in watts (W). In mathematical terms, Power can be computed as

P = VI

Where P is the power in watts (W), V is the voltage across the resistor in volts (V) and I is the current, in amperes (A) flowing through the resistor. in the previous example, the power dissipated by the 330Ω resistor is 5V • 0.01515A, 0.07575W, or 75.75mW. The resistors supplied with most kits have a power rating of 1/4W (250mW). A 1/4W power rating is sufficient for our current example and most Arduino circuits you will encounter.

LED

LEDs are semiconductor devices that emit light when current flows through them. as its name suggests, an LED only allows current to flow in one direction, from anode to cathode, in the direction of the arrow of the diode symbol. Unlike resistors, an LEDs voltage across it leads is not linearly proportional to the current through the device and we have to look at its specification sheet to determine how the LED will perform within a circuit.

Red LED
A standard 20 mA red LED

Here is a sample datasheet for a standard 20mA LED:

YSL-R531R3D-D2

As can be seen from the data sheet, the forward voltage across the LED, that is the voltage across the LED when 20mA of current is flowing from the anode to the cathode, is between 1.8 and 2.2 volts. Also, it is suggested to limit the current between 16 to 18 mA in normal operation.

Computing the Resistor Value

Apart from Ohm’s law and the power rating formula, we need a bit more information to find a resistor value that will limit the current flow within the LED to a value not exceeding 18mA. Kirchkoff’s Voltage Law states that the sum of voltages around a closed circuit loop is 0V. Current goes in the counter-clockwise direction in this circuit, from the positive end of the power source to the negative end and the voltage drop around the power source is negative since voltage does not drop but increases around it. Redrawing our LED circuit when the digital output pin is HIGH and replacing the pin by a 5V source we get:

Kirchkoff

The sum of all voltages around the circuit is:

-5V + 1.8V + VR1 = 0V

Solving for VR1, we get

VR1 = 5V – 1.8V = 3.2V

Thus, we know that we want 18mA to flow through both LED and resistor and that the voltage across the resistor is 3.2V. Going back to Ohm’s law we know that

R1 = VR1 / I = 3.2V / 0.018A = 177Ω

This is the smallest resistor value to obtain the maximum optimal amount of current through the circuit. Resistors don’t come in all possible values. The most common values are the following values multiplied by powers of 10: 10, 15, 22, 33, 47, 68. The value just higher than 177Ω is 220Ω. Using this new value, we get

I = VR1 / R1 = 3.2V / 220Ω = 14.5mA

A value close to the optimal value suggested by the LED manufacturer. The value shown in the first circuit, 330Ω is the value used in the SparkFun kit I used for this experiment. This value limits the current to a value of 9.7mA which does allow the LED to emit light, but at a dimmer intensity.

There is Beauty in Geeky Things!

Welcome to my blog about sharing my life long passion with electronics, software design and my newfound passion with micro-controllers and their open hardware and software platforms. This blog is a series of tutorials and experiments to allow hobbyists understand the basics of electronic design and software programming and be able to reproduce the experiments, add to them and create their own circuits and programs.

Experiments in this blog make use of the Arduino Uno, a micro-controller, and a few electronic components that come with starter kits that can be found on the Internet. Experiments were tested using SparkFun Inventor’s Kit. The kit comes with a SparkFun RedBoard, a version of the Arduino Uno micro-controller, a solderless breadboard, jumper wires and electronic components such as LEDs (Light Emitting Diodes), resistors, light and temperature sensors, and more.

I recommend to the beginning enthusiast to procure a kit, whether from Sparkfun or other suppliers as they contain instructions on how to setup the Arduino, on how to get necessary software from the Internet, and how to use the software to program the micro-controller and make it work. Here is a non-exhaustive list of starter kits found on the Internet in no particular order.

Once equipped with a kit, we will embark on a series of circuits and programs that will complement and further your starter kit experience with explanations, tips and ideas.

Progress lies not in enhancing what is, but in advancing toward what will be. — Khalil Gibran

Place_Jacques-Cartier_Jan_2006