Arduino: A Quick-Start Guide, Second Edition (2015)

Part II. Eleven Arduino Projects

Chapter 4. Building a Morse Code Generator Library

You now know enough about the Arduino development environment and about blinking LEDs to start a bigger project. In this chapter, we’ll develop a Morse code generator that reads text from the serial port and outputs it as light signals using an LED.

By building this project, you’ll deepen your understanding of serial communication between the Arduino and your computer. You’ll also learn a lot about the typical Arduino development process: how to use existing libraries and how to structure bigger projects into your own libraries. At the end, you’ll be able to create a library that is ready for publishing on the Internet.

What You Need

1. An Arduino board such as the Uno, Duemilanove, or Diecimila

2. A USB cable to connect the Arduino to your computer

3. A speaker or a buzzer (optional)

Learning the Basics of Morse Code

Morse code was invented to turn text into sounds.^[50] In principle, it works like a character set encoding, such as ASCII. But while ASCII encodes characters as numbers, in Morse code they’re sequences of dots and dashes (also called dits and dahs). Dits are shorter in length than dahs. An Ais encoded as · – and – – · · is Z.

Morse code also specifies a timing scheme that defines the length of the dits and dahs. It specifies how long the pauses between symbols and words have to be. The base unit of Morse code is the length of a dit, and a dah is as long as three dits. You insert a pause of one dit between two symbols, and you separate two letters by three dits. You insert a pause of seven dits between two words.

To transmit a message encoded in Morse code, you need a way to emit signals of different lengths. The classic approach is to use sounds, but we will use an LED that is turned on and off for varying periods of time. Sailors still transmit Morse code using blinking lights.

Let’s implement a Morse code generator!

Building a Morse Code Generator

The main part of our library will be a C++ class named Telegraph. In this section, we’ll define its interface, but we will start with a new sketch that looks as follows:

This is the most minimalistic Arduino program possible. It doesn’t do anything except define all mandatory functions, even if they are empty. We do this so we can compile our work in progress from time to time and check whether there are any syntactical errors. Save the sketch asTelegraphLibrary, and the IDE will create a folder named TelegraphLibrary and a file named TelegraphLibrary.ino in it. All the files and directories we need for our library will be stored in the TelegraphLibrary folder.

Now open a new tab, and when asked for a filename, enter telegraph.h. Yes, we will create a good old C header file. (To be precise, it will even be a C++ header file.)

Ah, obviously object-oriented programming is not only for the big CPUs anymore! This is an interface description of a Telegraph class that you could use in your next enterprise project (provided that you need to transmit some information as Morse code, that is).

We start with the classic double-include prevention mechanism; that is, the body of the header file defines a preprocessor macro named __TELEGRAPH_H__. We wrap the body (that contains this definition) in an #ifndef so that the body is only compiled if the macro has not been defined. That way, you can include the header as many times as you want, and the body will be compiled only once.

The interface of the Telegraph class consists of a public part that users of the class have access to and a private part that only members of the class can use. In the public part, you find two things: a constructor that creates new Telegraph objects and a method named send_message that sends a message by emitting it as Morse code. In your applications, you can use the class as follows:

In the first line, we create a new Telegraph object that communicates on pin 13 and emits dits that are 200 milliseconds long. Then we emit the message “Hello, world!” as Morse code. This way, we are able to send whatever message we want, and we can change easily the pin and the length of a dit.

Now that we have defined the interface, we will implement it.

Fleshing Out the Morse Code Generator’s Interface

Declaring interfaces is important, but it’s as important to implement them. Create a new tab and enter the filename telegraph.cpp.

This is the right place to explain why we’ve used TelegraphLibrary and not Telegraph as the sketch’ name, even though it’d be a more natural choice. The reason is that the Arduino IDE turns every sketch (ending with .ino) into a C++ file (ending with .cpp). For a sketch namedTelegraph.ino it generates a C++ file named Telegraph.cpp. In a case-insensitive file system, this conflicts with a file named telegraph.cpp, and it leads to some strange error messages.

Enter the following code now in the newly created tab:

Like most C++ programs, ours imports some libraries first. Because we need functions such as toupper later, we include ctype.h, and we have to include telegraph.h to make our class declaration and its corresponding function declarations available. But what is Arduino.h good for?

Until now we haven’t thought about where constants such as HIGH, LOW, or OUTPUT came from. They are defined in several header files that come with the Arduino IDE, and you can find them in the hardware/arduino/cores/arduino directory of the IDE. Have a look at Arduino.h (in older Arduino versions this file was named WProgram.h). It contains all the constants we have used so far and many more. It also declares many useful macros and the Arduino’s most basic functions.

When you edit regular sketches, you don’t have to worry about including any standard header files, because the IDE does it automatically behind the scenes. As soon as you create more complex projects that contain “real” C++ code, you have to manage everything yourself. You have to explicitly import all the libraries you need, even for basic stuff such as the Arduino constants.

After importing all necessary header files, we define two string arrays named LETTERS and DIGITS. They contain the Morse code for all letters and digits, and we’ll use them later to translate regular text into Morse code. Before we do that, we define the constructor that is responsible for creating and initializing new Telegraph objects:

The constructor expects two arguments: the number of the pin the Morse code should be sent to and the length of a dit measured in milliseconds. Then it stores these values in corresponding instance variables, calculates the correct length of a dah, and turns the communication pin into an output pin.

You’ve probably noticed that all private instance variables start with an underscore. I like that convention personally, but it isn’t enforced by C++ or the Arduino IDE.

Outputting Morse Code Symbols

After everything has been initialized, we can start to output Morse code symbols. We use several small helper methods to make our code as readable as possible:

The function output_code takes a Morse code sequence consisting of dots and dashes and turns it into calls to dit and dah. The dit and dah methods then print a dot or a dash to the serial port and delegate the rest of the work to output_symbol, passing it the length of the Morse code symbol to be emitted. output_symbol sets the output pin to HIGH for the length of the symbol, and then it sets it back to LOW. Everything works exactly as described in the Morse code timing scheme, and only the implementation of send_message is missing:

send_message outputs a message character by character in a loop. In line 3, we turn the current character into uppercase, because lowercase characters are not defined in Morse code (that’s why you can’t implement a chat client using Morse code). Then we check whether the current character is a letter using C’s isalpha function. If it is, we use the character to determine its Morse code representation that is stored in the LETTERS array. To do that, we use an old trick: in the ASCII table, all letters (and digits) appear in the correct order—that is, A=65, B=66, and so on. To transform the current character into an index for the LETTERS array, we have to subtract 65 (or ’A’) from its ASCII code. When we have determined the correct Morse code, we pass it to output_symbol and delay the program for the length of a dah afterward.

The algorithm works exactly the same for outputting digits; we only have to index the DIGITS array instead of the LETTERS array, and we have to subtract the ASCII value of the character ’0’.

In line 10, we check whether we received a blank character. If yes, we print a blank character to the serial port and wait for seven dits. All other characters are ignored: we only process letters, digits, and blanks. At the end of the method, we send a newline character to the serial port to mark the end of the message.

Installing and Using the Telegraph Class

Our Telegraph class is complete, and we should now create some example sketches that actually use it. This is important for two reasons: we can test our library code, and for users of our class it’s good documentation for how to use it.

The Arduino IDE looks for libraries in two places: in its global libraries folder relative to its installation directory and in the user’s local sketchbook directory. During development, it’s best to use the local sketchbook directory. You can find its location in the IDE’s Preferences (see Figure 14,Find the sketchbook location in the Preferences). Create a new directory named libraries in the sketchbook directory.