Preprocessor Directives

We’ve seen a couple of preprocessor directives already: #include and #define are both handled by the preprocessor. And the name “preprocessor” probably gives you a hint about its role in compiling your code. These directives are processed before your code is compiled.

The #include directive is used to bring in code defined in a separate file. After inclusion, it looks to the compiler as if you had typed in that external file as part of your own code.

The #define directive, as we’ve been using it, puts a human-friendly name on some literal. We can then use the name in our code rather than remembering the correct literal every time. And if we ever need to change that value, say, move an LED connection to a different pin on our controller, we only need to change it once. As with #include, the preprocessor replaces each instance of a #define name with its literal as though you had typed the literal directly.

For our car, let’s use #define for the pins on our navigation joystick as we have with other connected peripherals:

#define LEFT_BTN  12
#define RIGHT_BTN  9
#define FWD_BTN   10
#define BKWD_BTN  11

I should point out that you can use #define with values other than numbers. Perhaps you have a standard error message or text response. Those can be defined, too:

#define GOOD_STATUS  "OK"
#define BAD_STATUS   "ERROR"
#define NO_STATUS    "UNKNOWN"

Knowing how #define works with the preprocessor also explains why we don’t put a semicolon at the end. We don’t want the semicolon showing up in our code, after all.

Preprocessor Macros

You can take #define a step further as well. Not only does it handle strings, it can handle small pieces of logic, almost like a function. These snippets are often referred to as macros to distinguish them from actual functions. A macro (or macroinstruction) transforms some bit of input to a corresponding bit of output, typically via substitutions. Macros are not function calls. Macros are not pushed onto or popped off of the stack.

Macros are great when you have a repeated bit of code that just doesn’t rise to the level of needing a function. They are also great when you want your snippet to remain data-type agnostic. For example, consider a simple macro to determine the minimum of two values. Here’s the definition and an example of how to use it:

#define MIN (x,y) x < y ? x : y

int main() {
  int smaller1 = MIN(9, 5);
  float smaller2 = MIN(1.414, 3.1415);
  // ...
}

To create the macro, we use #define and a name, like before, but then we supply a variable (or variables) in parentheses. Whatever arguments you pass to the macro replace the variables in the macro’s snippet. That snippet, in turn, replaces the spot where it was called. It’s as if you had typed the following:

int main() {
  int smaller1 = 9 < 5 ? 9 : 5;
  float smaller2 = 1.414 < 3.1415 ? 1.414 : 3.1415;
}

That simple replacement process can be powerful. But do be careful. Because the replacement is so simple, you can create problems if you pass complex expressions to your macro. If, say, your expression uses an operator of lower precedence than one used in your macro, the intended outcome can be wrong or even uncompilable. You can avoid some of these problems with judicious use of parentheses, like this:

#define MIN (x,y) (x) < (y) ? (x) : (y)

Even then you can create some odd code by passing just the right (er, wrong) expressions. The GNU documentation on C and the C preprocessor even has an entire section devoted to macro pitfalls.

We don’t need any macros just yet, but they’re common enough that I want you to recognize them if you find them in the wild. The C preprocessor is actually quite an interesting entity in its own right. It’s a great target for some independent research after you finish this book!

Custom Type Definitions

Beyond constants and macros, libraries often make use of another feature of C: the typedef operator. You can use typedef to assign an alias to some other type. That might sound unnecessary, and it technically is, but there are several cases where it is very convenient and leads to more readable, maintainable code.

We saw the use of some of these typedef aliases in Chapter 10. The byte, uint8_t, and uint32_t specifiers were all created with typedef. If the Arduino environment didn’t provide those for you, you could create them yourself like so:

typedef unsigned char byte;
typedef unsigned char uint8_t;
typedef unsigned long int uint32_t;

You can also use typedef with the struct keyword to make more palatable names for your custom, rich data types. For example, we could have used typedef in “Defining Structures” and defined our transaction like this:

typedef struct transaction {
  double amount;
  int day, month, year;
} transaction_t;

// Transaction variables can now be declared like this:
transaction_t bill;
transaction_t deposit;

This feature is not something strictly necessary for our simple library, but many libraries do use typedef to provide names for types that make more sense in the context of the library or that are simply easier to work with. Let’s go ahead and define a type for any variables that might store one of our direction constants:

typedef signed char direction_t;

We’ll stick with the signed version of char since we might find uses for negative values down the road. Negative numbers make great error codes if you are otherwise only expecting positive numbers, for example. Now let’s use our new type to create some typed constants:

const direction_t STOP     = 0;
const direction_t LEFT     = 1;
const direction_t RIGHT    = 2;
const direction_t FORWARD  = 3;
const direction_t BACKWARD = 4;

Recall the discussion of const versus #define in “Constants: const versus #define”. This is one of those spots where we aren’t really doing anything that demands one approach or the other, but the const approach does add some inherent documentation to our code that could be useful to other readers. And I should say that 90% of the time the first “other reader” that sees your code is you, but you after a few weeks or months away from the project. Hints about your intentions like the direction_t type can be very useful in jogging your own memory.

Our Car Project

Let’s get going! This will be our “version one” project with some extra abstraction that should help as we break up this project into reusable pieces. (You can take a look at version 0 if you want to start with a simple proof of functionality.) As you work with your own project, you may not have the motors wired up exactly as I do. Your navigation input (buttons or a joystick) might be connected a little differently. Test out your setup and don’t be afraid of changing which pins get set HIGH or LOW in the various driving functions. Happily, that can all be tweaked here in software. The end goal is simply to get your car to roll forward when you push the joystick up.

Here’s version 1 of our car build. As always, you can type this up yourself or just open ch11/car1/car1.ino:

// Define the pins we're using for the joystick and the motor
#define LEFT_BTN  12
#define RIGHT_BTN  9
#define FWD_BTN   10
#define BKWD_BTN  11

#define AIN1 4
#define AIN2 5
#define BIN1 6
#define BIN2 7

// Define our direction type
typedef char direction_t;

// Define our direction constants
const direction_t STOP     = 0;
const direction_t LEFT     = 1;
const direction_t RIGHT    = 2;
const direction_t FORWARD  = 3;
const direction_t BACKWARD = 4;

void setup() {
  // Tell our board we want to write to the built-in LED
  pinMode(LED_BUILTIN, OUTPUT);

  // Accept input from the joystick pins
  pinMode(LEFT_BTN, INPUT_PULLUP);
  pinMode(RIGHT_BTN, INPUT_PULLUP);
  pinMode(FWD_BTN, INPUT_PULLUP);
  pinMode(BKWD_BTN, INPUT_PULLUP);

  // Send output to the motor pins
  pinMode(AIN1, OUTPUT);
  pinMode(AIN2, OUTPUT);
  pinMode(BIN1, OUTPUT);
  pinMode(BIN2, OUTPUT);

  // And make sure our LED is off
  digitalWrite(LED_BUILTIN, LOW);
}

void allstop() {
  digitalWrite(AIN1, LOW);
  digitalWrite(AIN2, LOW);
  digitalWrite(BIN1, LOW);
  digitalWrite(BIN2, LOW);
}

void forward() {
  digitalWrite(AIN1, LOW);
  digitalWrite(AIN2, HIGH);
  digitalWrite(BIN1, HIGH);
  digitalWrite(BIN2, LOW);
}

void backward() {
  digitalWrite(AIN1, HIGH);
  digitalWrite(AIN2, LOW);
  digitalWrite(BIN1, LOW);
  digitalWrite(BIN2, HIGH);
}

void left() {
  digitalWrite(AIN1, HIGH);
  digitalWrite(AIN2, LOW);
  digitalWrite(BIN1, LOW);
  digitalWrite(BIN2, LOW);
}

void right() {
  digitalWrite(AIN1, LOW);
  digitalWrite(AIN2, LOW);
  digitalWrite(BIN1, LOW);
  digitalWrite(BIN2, HIGH);
}

direction_t readDirection() {
  if (digitalRead(FWD_BTN) == LOW) {
    return FORWARD;
  }
  if (digitalRead(BKWD_BTN) == LOW) {
    return BACKWARD;
  }
  if (digitalRead(LEFT_BTN) == LOW) {
    return LEFT;
  }
  if (digitalRead(RIGHT_BTN) == LOW) {
    return RIGHT;
  }
  // No buttons were pressed, so return STOP
  return STOP;
}

void loop() {
  direction_t dir = readDirection();
  if (dir > 0) { // Driving!
    digitalWrite(LED_BUILTIN, HIGH);
    switch (dir) {
      case FORWARD:
        forward();
        break;
      case BACKWARD:
        backward();
        break;
      case LEFT:
        left();
        break;
      case RIGHT:
        right();
        break;
    }
  } else {
    // Stopping, or eventually we could handle errors, too
    digitalWrite(LED_BUILTIN, LOW);
    allstop();
  }
}

Feel free to take a break from the book at this point and just have some fun. :) Can you drive both forward and backward? When you move the joystick left or right, does the car turn the way you want? Can you parallel park between two stuffed animal obstacles? It might feel a little awkward following your car around with the tethered joystick, but we’ll fix that shortly.

Code (.ino) Files

To start, let’s save this project under a new name so that we have a backup in case something goes awry and we want to refer back to a working project. From the “File” menu in the Arduino IDE, select the “Save As…” option. I chose the highly creative and original name car2. You are free to be as creative or even more so if the muse strikes.

Now let’s take all five of our driving functions and move them to their own file. To add a new file, use the downward pointing triangle button on the right-hand side near the top. That button opens a small menu, as shown in Figure 11-3. Select “New Tab” from that menu.

Figure 11-3. Creating a new tab in the Arduino IDE

Next, you’ll be prompted to name the tab, as shown in Figure 11-4. Enter the name drive.ino in the field and then click the OK button.

Figure 11-4. Naming our new file

You should now have a new tab named “drive” (with no suffix showing). Go ahead and cut the five driving functions (including allstop()) from the “car2” tab and then paste them into our new “drive” tab. That tab will end up with the following code (ch11/car2/drive.ino):

void allstop() {
  digitalWrite(AIN1, LOW);
  digitalWrite(AIN2, LOW);
  digitalWrite(BIN1, LOW);
  digitalWrite(BIN2, LOW);
}

void forward() {
  digitalWrite(AIN1, LOW);
  digitalWrite(AIN2, HIGH);
  digitalWrite(BIN1, HIGH);
  digitalWrite(BIN2, LOW);
}

void backward() {
  digitalWrite(AIN1, HIGH);
  digitalWrite(AIN2, LOW);
  digitalWrite(BIN1, LOW);
  digitalWrite(BIN2, HIGH);
}

void left() {
  digitalWrite(AIN1, LOW);
  digitalWrite(AIN2, HIGH);
  digitalWrite(BIN1, LOW);
  digitalWrite(BIN2, LOW);
}

void right() {
  digitalWrite(AIN1, LOW);
  digitalWrite(AIN2, LOW);
  digitalWrite(BIN1, HIGH);
  digitalWrite(BIN2, LOW);
}

That’s actually all the work required to separate these pieces of code! You now have your first multifile Arduino project. Click the Verify (checkmark) button to make sure your project still compiles in its new, two-file configuration. Everything should still work. You can even upload this to your controller and still drive your car.

If the project does not verify or upload, check to make sure you didn’t drop a curly brace or perhaps grab an extra line from the original file. You should also make sure the name you picked for your newly separated file ends with that .ino extension.

The Arduino IDE performs a little magic for us with .ino files. Our main project file (car2.ino in the car2 folder, in this case) is prepared first. Any other .ino files will then be included in alphabetical order. You may have noticed that our drive.ino file has no #include statements. And yet, we clearly use the pin constants defined in our main file. As far as the compiler is concerned, there is only one large .ino file to compile, so successive .ino files see all of the functions, #defines, and global variables from the files that came before. At this time, there is no way to change the order of the separate .ino files; they are always incorporated alphabetically.

Header Files

So how can all these separate files work together so seamlessly? The IDE adds one more piece of magic before loading these separate files. It creates a header file with forward declarations of all of the functions and global variables in your .ino file. Forward declarations are brief descriptions of what your function is named, what parameters it has, and what type of value it will return. They allow separate files to use a function without needing to have its full implementation. Each header, in turn, is automatically included in your main project file.

You can see the effect of this in our simple two-tab project. The drive.ino file does not need to include any extra information to make use of our #define pin entries. And the code in our main car2.ino file can call the functions defined in drive.ino without worrying about the ordering or specific location of the functions. In the end, both files fit together perfectly to complete our project.

You can also create your own header files. This can be nice for housekeeping. For example, if you have many #define statements, you could place them in their own header. Or if you want a low-tech means of sharing some directives between projects, you can make a copy of a header and put it in another project. It is largely up to you what makes the most sense for your own projects. Many successful makers out there have dozens or hundreds of projects each with one single .ino file. I just want to make sure you know how to split things into more manageable pieces if that one big file starts to overwhelm you.

In service of that goal, let’s break up our main project just a little more. Let’s try the trick of putting some of our #define directives in their own header file. We’ll move the eight pin constants. Create a new tab as before, and name it pins.h when prompted. The new tab should show the full name of the file, pins.h, to help distinguish it from .ino files that hide the extension.

Cut the eight #define lines and the relevant comments from car2 and paste them into pins.h. The result should look like ch11/car2/pins.h:

// Define the pins we're using for the joystick and the motor

#ifndef PINS_H
#define PINS_H

#define LEFT_BTN  12
#define RIGHT_BTN  9
#define FWD_BTN   10
#define BKWD_BTN  11

#define AIN1 4
#define AIN2 5
#define BIN1 6
#define BIN2 7

#endif /* PINS_H */

Now we just need to add an include statement to our car2 tab at the top of our file:

#include "pins.h"

You can check your work against my version 2. Your project should still verify (and upload) just as before. Feel free to give it a try and make sure you can still drive your car.

Again, divvying up a project is not a requirement or something you always do with large files, but it can be helpful. It allows you to concentrate on one part of your code without accidentally changing another part. If you collaborate with other programmers, working on separate files can also make it easier to combine your efforts at the end. In the end, though, it really is up to you and what you feel comfortable with.

Facilitating Communication

Our robot car is spiffy, but following it around with a tethered joystick is clunky. A radio-controlled robot car would be even spiffier! We can do that, and using a library to manage that radio communication is a great way to guarantee we don’t cross any signals—literally. We can use a library to make sure multiple parties have access to common definitions (say, the value for driving “forward”). We can also put the rules of a protocol into a library’s functions. It’s a bit like making sure everyone is speaking the same language.

Libraries can supply more than the vocabulary of this hypothetical language. They can also enforce the rules of conversation. Who speaks first? Who speaks next? Is a response required? Can there be more than one listener? You answer questions like these with the functions you write in your library. As long as two (or more) projects use the same library, the details you encoded in the library’s functions will make sure everyone plays nicely together.

Let’s create a library to send and receive radio signals. We’ll create two separate projects that both use this library. We’ll start by replacing the joystick that is currently wired to our car with a radio component. Then we’ll create a controller project that pairs our newly liberated joystick with a similar radio. This does mean we need two microcontrollers, by the way. I’ll use another Metro Mini, but they don’t have to be identical. If you have some other controller lying around that is compatible with our radio and can use our library, any combination of controllers should work.

Retrofitting Our Car

Let’s swap out the joystick for a radio transceiver. I’m using the nicely packaged RFM69HCW high-power breakout from Adafruit. It’s about $10 and is reasonably straightforward to connect. Plus, it comes with some nice features like encrypted transmissions that can only be decrypted by a similar chip with the same encryption key (that you provide in code). Figure 11-5 shows the wiring diagram for our microcontroller, the motor driver, and our radio. I had to relocate several of the DRV8833 connections as the RFM69HCW requires the use of specific pins on our Metro Mini microcontroller (more on that in “Our radio-control library header”).

Figure 11-5. Wiring for the robot car with radio transceiver

Of course the power and ground pins should be connected as well. I used a 9V for the microcontroller (which in turn supplies power to the radio) and a separate power supply for the DRV8833. The lonely green wire attached to the top of the RFM69HCW is just a three-inch piece of wire serving as the simplest possible antenna.¹

Figure 11-6 shows the assembled components, all ready to roll with no wires attached!

Figure 11-6. Our wire-free robot car

Well, no wires to a joystick, that is. The breadboard is rather lousy with wires. This is a bigger project than we’ve tackled so far. If a radio-controlled car isn’t up your alley, feel free to skip to the next chapter. But before you go, check out “Creating the Library” on creating the library code and its header file.

I’m using two separate power supplies to keep the motors separate from the microcontroller and the radio. If you have more experience powering Arduino projects and want to use a different configuration, go right ahead! The important part is that we have our radio ready to receive driving instructions.

Creating a Controller

We also need a new project to take input from our joystick and send that information out over the radio. Figure 11-7 shows the wiring. Only one battery is required for the controller; the radio can be safely powered from the 5V pin of our microcontroller.

Figure 11-7. Wiring for the radio controller

I powered the controller with a USB power pack plugged into the Metro Mini. Figure 11-8 shows the final result.

Figure 11-8. Our wire-free controller

Not the most glamorous of gadgets, but it does send radio signals! At least, it will once we add a little code.

Creating the Library

The code for both our car and our controller will require our radio library, so let’s start there. We’ll be creating one header file and one .cpp file to accommodate the C++-centric nature of the Arduino IDE. The actual code will still be (mostly) vanilla C, it just needs to live in a file with that .cpp extension.

How you go about writing this code is really up to you. You can write everything in one file and then separate out the parts that go into the header (much like we did earlier in this chapter). You can also use the header as a sort of outline or plan. Fill out the header with your constants and names of your functions, then go create the .cpp file to implement those functions. Regardless of which path sounds better to you, we need to put the files in a specific place before the IDE will recognize them.

The libraries folder

We place all of the files for our library inside one folder that goes in the libraries folder wherever your Arduino sketches live. On my Linux box, that’s the Arduino folder in my home directory. If you’re not sure where that folder is on your system, you can check the preferences in the Arduino IDE. From the File menu, select the Preferences option. You should see a dialog similar to Figure 11-9. Notice the “Sketchbook location” toward the top. That’s where the libraries folder needs to go. If there isn’t one there already, go ahead and create that now.

Figure 11-9. The Sketchbook location preference setting

It’s actually useful that we’re looking at this folder now, since we need to manually install the library for our radio breakout. It will go in this same folder. I’m using the radio library written by the folks at Adafruit.² Download the ZIP archive from the green “Code” drop-down button. Unzip that file and rename the resulting folder RadioHead. Place this RadioHead folder in the libraries folder, and that’s it.

Well, that’s it for the radio library. We still need to make a folder for our own, yet to be written, library. Inside the libraries folder, create a new folder and pick a name for your custom library. Since this is a radio control library for a robot car, and the title of this book ends in those two letters, I chose to name mine SmalleRC. You are under no pressure to use such delightful, nerdy puns for your library names, by the way. This is where the “custom” adjective comes in. Customize your library however you like!

#ifndef SMALLERC_H                    
#define SMALLERC_H

#include "Arduino.h"                  
#include <SPI.h>                      
#include <RH_RF69.h>                  

#define RF69_FREQ 915.0               
#define RFM69_CS      4
#define RFM69_INT     3
#define RFM69_RST     2
#define LED          13

#define rc_INIT_SUCCESS  1            
#define rc_INIT_FAILED  -1
#define rc_FREQ_FAILED  -2

// Define our direction type
typedef signed char direction_t;      

// Define our directions
const direction_t rc_STOP     = 0;
const direction_t rc_LEFT     = 1;
const direction_t rc_RIGHT    = 2;
const direction_t rc_FORWARD  = 3;
const direction_t rc_BACKWARD = 4;

char rc_start();                      
void rc_send(int d);
int  rc_receive();

#endif /* SMALLERC_H */

#include "SmalleRC.h"                                 

RH_RF69 rf69(RFM69_CS, RFM69_INT);                    

char rc_start() {                                     
  pinMode(LED, OUTPUT);
  pinMode(RFM69_RST, OUTPUT);
  digitalWrite(RFM69_RST, LOW);

  // manual reset
  digitalWrite(RFM69_RST, HIGH);
  delay(10);
  digitalWrite(RFM69_RST, LOW);
  delay(10);

  if (!rf69.init()) {
    return rc_INIT_FAILED;
  }

  if (!rf69.setFrequency(RF69_FREQ)) {
    return rc_FREQ_FAILED;
  }

  // range from 14-20 for power
  // 2nd arg must be true for 69HCW
  rf69.setTxPower(17, true);

  // The encryption key is up to you, but must be
  // the same for both the car and the controller
  uint8_t key[] = {                                   
    0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
    0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
  };
  rf69.setEncryptionKey(key);

  pinMode(LED, OUTPUT);
  return rc_INIT_SUCCESS;
}

void rc_send(direction_t d) {                         
  uint8_t packet[1] = { d };
  rf69.send(packet, 1);
  rf69.waitPacketSent();
}

direction_t rc_receive() {                            
  uint8_t buf[RH_RF69_MAX_MESSAGE_LEN];
  uint8_t len = sizeof(buf);
  if (rf69.recv(buf, &len)) {
    if (len == 0) {
      return -1;
    }
    buf[len] = 0;
    return (direction_t)buf[0];
  }
  return STOP;
}

Updating the Car Project

Now we need to write the code for the car. (Feel free to review the physical setup of the car and breakouts in “Retrofitting Our Car”.) Essentially, we are going to replace the logic for polling the joystick with a call to check for data from the radio. We’ll pause for a few milliseconds to avoid starting and stopping the motors too quickly. Otherwise, we’ll run a pretty tight loop so that the car feels responsive to our remote controller.

I based this version (car3) on the car2 project, which had the separate pins.h and drive.ino files. We no longer need the pins for the joystick in this project, so the header file is a bit shorter:

#ifndef PINS_H
#define PINS_H

#define AIN1 9
#define AIN2 8
#define BIN1 6
#define BIN2 7

#endif /* PINS_H */

The driving functions are completely unchanged so I’ll leave those out, but you can review the code (“Code (.ino) Files”) if you want. The code for the main car3.ino file should feel familiar, but obviously we need to include the header file of our new radio library:

#include "pins.h"
#include "SmalleRC.h"

void setup() {
  Serial.begin(115200);
  // Send output to the motor pins
  pinMode(AIN1, OUTPUT);
  pinMode(AIN2, OUTPUT);
  pinMode(BIN1, OUTPUT);
  pinMode(BIN2, OUTPUT);

  if (rc_start() != rc_INIT_SUCCESS) {
    Serial.println("Failed to initialize radio.");
  }
}

void loop() {
  direction_t dir = rc_receive();
  if (dir > 0) { // Driving!
    switch (dir) {
      case rc_FORWARD:
        forward();
        break;
      case rc_BACKWARD:
        backward();
        break;
      case rc_LEFT:
        left();
        break;
      case rc_RIGHT:
        right();
        break;
    }
    delay(20);
  } else {
    // Stopping, or eventually we could handle errors, too
    allstop();
  }
}

Notice that I’m using the new navigation constants (like rc_LEFT) defined in the SmalleRC.h file. But that’s really all the code we need now to drive our car! This is one of the many benefits from separating out chunks of common code. By building on that shared code, you can more quickly create some very interesting projects.

There’s no good way to test this new car3 project just yet, but go ahead and upload it to your microcontroller. If nothing else, you can use the Serial Monitor tool to ensure that there were no errors in starting up the radio to receive. I went with the “no news is good news” approach to errors in the setup() function, but feel free to alter that a bit to produce a success message if you like.

Getting It Under Control

Next up is getting the controller programmed. (Again, look back at “Creating a Controller” if you still need to build the physical remote control.) Here we take the joystick polling and instead of sending the results to the motors, we broadcast any directional information over our radio. This is a pretty small project thanks to the library, so I left it in a single ch11/controller/controller.ino file:

#include "SmalleRC.h"

#define LEFT_BTN  9
#define RIGHT_BTN 7
#define FWD_BTN   8
#define BKWD_BTN  6

void setup() {
  Serial.begin(115200);
  // Accept input from the joystick pins
  pinMode(LEFT_BTN, INPUT_PULLUP);
  pinMode(RIGHT_BTN, INPUT_PULLUP);
  pinMode(FWD_BTN, INPUT_PULLUP);
  pinMode(BKWD_BTN, INPUT_PULLUP);

  if (rc_start() != rc_INIT_SUCCESS) {
    Serial.println("Failed to initialize radio.");
  }
}

direction_t readDirection() {
  if (digitalRead(FWD_BTN) == LOW) {
    return rc_FORWARD;
  }
  if (digitalRead(BKWD_BTN) == LOW) {
    return rc_BACKWARD;
  }
  if (digitalRead(LEFT_BTN) == LOW) {
    return rc_LEFT;
  }
  if (digitalRead(RIGHT_BTN) == LOW) {
    return rc_RIGHT;
  }
  // No buttons were pressed, so return STOP
  return rc_STOP;
}

void loop() {
  direction_t dir = readDirection();
  rc_send(dir);
  delay(10);
}

We could have put the logic of the readDirection() function right inside our loop() function, but I like how concise loop() is with this small abstraction.

Try verifying this new project and if you hit any snags, add a few more Serial.println() statements. And remember, you can also add those to your library code if needed.

Go Driving!

No code. No diagrams. No instructions. Just another point in this chapter where I wholly encourage you to go play. :) Try powering up both projects and see what happens when you move the joystick. There are definitely things that could go wrong! If the wiring isn’t quite right, for example, the car might move, but not in the direction you meant. (I accidentally swapped the right-side motor input pins when moving the project to a full-size breadboard, for example. The right wheel turned, but in the wrong direction.) Or if we have the wrong pins connected to the joystick, we might not send any signal at all.

If the car doesn’t budge, it’s time yet again to break out your debugging skills. You can have both projects connected to your computer at the same time, by the way. They will simply be on different serial ports. (Remember, you can set which port you use for your microcontroller through the Tools menu in the Arduino IDE.) You can use Serial.println() statements to make sure your inputs, sends, receives, and drives are all doing what you expect them to do. Just watch out for success! When you do get things working, it’s surprisingly easy to drive your car right off the desk and leave a string of electronics dangling from your USB cable. Or, you know, so I’m told.

Documentation and Distribution

Once your library is working and you’ve had enough fun zipping around your room, it’s time to think about adding a little documentation to your project. Documentation is great. Not just for other programmers who might use your library, either. If you step away from a project even just for a few days, any documentation you wrote can be surprisingly useful for helping you get your own mind back up to speed.

rc_INIT_SUCCESS LITERAL1
rc_INIT_FAILED  LITERAL1
rc_FREQ_FAILED  LITERAL1

direction_t KEYWORD1

rc_STOP LITERAL1
rc_LEFT LITERAL1
rc_RIGHT    LITERAL1
rc_FORWARD  LITERAL1
rc_BACKWARD LITERAL1

rc_start    KEYWORD2
rc_send KEYWORD2
rc_receive  KEYWORD2