Arduino Sketches: Tools and Techniques for Programming Wizardry (2015)

Part III. Device-Specifi c Libraries

Chapter 21. Esplora

This chapter discusses the following functions of the Esplora library:

· writeRGB()

· writeRed()

· writeGreen()

· writeBlue()

· readRed()

· readGreen()

· readBlue()

· writeRGB()

· readSlider()

· readLightSensor()

· readTemperature()

· readMicrophone()

· readAccelerometer()

· readJoystickX()

· readJoystickY()

· readJoystickSwitch()

· readJoystickButton()

· readButton()

· noTone()

· readTinkerkitInputA()

· readTinkerkitInputB()

· readTinkerkitInput()

The hardware needed to use these functions includes:

· Arduino Esplora

· 2 x TinkerKit 3-wire cables

You can find the code download for this chapter at http://www.wiley.com/go/arduinosketches on the Download Code tab. The code is in the Chapter 21 folder and the filename is Chapter21.ino.

Introducing Esplora

Almost all Arduino devices are physical boards that are placed on a desk or inside an enclosure. To add electronics, you must either use a shield or a breadboard. The Arduino Esplora is a different beast.

Arduino is all about getting hands-on, and the Esplora goes a step further. It is a device that ends up in your hands, not on the desk. Get ready to pick it up and play with it.

The Esplora is an excellent device for users who do not want to get too involved in electronics because it integrates an amazing amount of peripherals. Although most Arduinos only have an on-board LED on pin 13, the Esplora has an LED on pin 13, an RGB LED, a light sensor, a temperature sensor and much, much more. Here is the entire list:

· Temperature sensor

· Light sensor

· Microphone

· Two-axis analog joystick (with center-push button)

· Four push buttons

· Three-axis accelerometer

· RGB LED

· Piezo buzzer

· Two TinkerKit inputs

· Two TinkerKit outputs

· LCD screen header

So what is a TinkerKit input or output? TinkerKit is a fantastic way of connecting components without needing to know anything about electronics. There are different modules: joysticks, accelerometers, potentiometers, Hall effect sensors, LEDs, servos, and relays to name a few. These modules can be connected to a port using standard cables; the Arduino Esplora has four ports.

As you can see, the Arduino Esplora has an amazing amount of components on the device, but this comes at a cost. The Arduino Esplora is designed to be held in your hand and has the look and feel of a console game pad. As such, it does not have any shield connectors (but does have a header for an optional LCD screen). It also does not have any prototyping space, meaning that adding components is difficult. There are no electronic input and output pins, and no headers to add components to. All Arduino Esploras are therefore alike, and therefore a library was written specifically for this device.

The Arduino Esplora Library

The Esplora library is available in Arduino IDE 1.0.4 and later. To import the library, use the Arduino IDE: Sketch Import Library Esplora, or add the library manually:

#include <Esplora.h>

After this file is imported, all the devices on the Arduino Esplora become available through the Esplora constructor. There is no need to create this object; it is defined automatically.

RGB LED

The Arduino Esplora has a high-power RGB LED on-board. A sketch can control this LED and create different colors by varying the output to each component. This is done automatically via PWM, and writing a value to the LED once keeps the LED on at the specified color until instructed otherwise.

To set the LED to a specific color, use writeRGB().

Esplora.writeRGB(red, green, blue);

The red, green, and blue parameters are ints and represent the brightness of the corresponding color. (Acceptable values ranging from 0 to 255 included.) It is possible to write a single color value using the writeRed(), writeGreen(), and writeBlue() functions.

Esplora.writeRed(value);

Esplora.writeGreen(value);

Esplora.writeBlue(value);

Again, each parameter is an int and accepts values between 0 and 255. Writing to one color does not affect the other components.

By writing an individual color, the sketch may no longer know what color value was written. For example, if the red value changes based on an external input, the main program might not know what the value of the red LED is. It is possible to read these values after writing them by using readRed(), readGreen(), and readBlue().

redResult = Esplora.readRed();

greenResult = Esplora.readGreen();

blueResult = Esplora.readBlue();

Each of these functions returns an int representing the brightness of the LED.

To turn the LED off, use writeRGB() with all parameters set at zero (the value of the red, green, and blue is off).

Esplora.writeRGB(0, 0, 0); // Turn the LED off

Sensors

The Arduino Esplora has an integrated linear potentiometer in the form of a slider. This component, connected to an analog-to-digital converter, can give values between 0 (0 Volts) to 1,023 (5 Volts). To read the value, use readSlider().

result = Esplora.readSlider();

This function does not take any parameters and returns an int, the value of the position of the potentiometer.

The Arduino Esplora also has a light sensor that is connected in the same way. It also returns values between 0 and 1,023; the more light, the higher the value.

result = Esplora.readLightSensor();

Also available on the list of sensors, the Esplora has a temperature sensor. The temperature can be read using readTemperature().

result = Esplora.readTemperature(scale);

The scale parameter is a constant, one of either DEGREES_C for Celsius or DEGREES_F for Fahrenheit. This function returns an int; returned values vary between –40° C and 150° C (or –40° F and 302° F).

The Esplora has something else uncommon for an Arduino; it has a microphone. The microphone is not designed to record sounds; instead, it gives an accurate reading of the amplitude of the ambient noise level. The value can be read with readMicrophone().

result = Esplora.readMicrophone();

This function takes no parameters and returns an int—the ambient sound level—on a scale of 0 to 1,023.

Finally, the Esplora also has an accelerometer: a small device that can detect the tilt of the device. Contrary to what some people believe from the name, an accelerometer does not calculate coordinate acceleration (a change in velocity); it measures proper acceleration: acceleration relative to gravity. It can therefore detect a tilt (a change in direction relative to gravity) but also movement. (For example, a falling device has limited acceleration attempting to counter gravitational pull.)

Values can be read from the accelerometer by using readAccelerometer().

value = Esplora.readAccelerometer(axis);

This function needs to be called for each axis individually. The axis is specified using the axis parameter and is one of X_AXIS, Y_AXIS, or Z_AXIS. It returns an int between –512 and 512. A result of zero means the axis is perpendicular to gravity: negative and positive values mean acceleration on the axis.

int x_axis = Esplora.readAccelerometer(X_AXIS);

int y_axis = Esplora.readAccelerometer(Y_AXIS);

int z_axis = Esplora.readAccelerometer(Z_AXIS);

Serial.print("x: ");

Serial.print(x_axis);

Serial.print("\ty: ");

Serial.print(y_axis);

Serial.print("\tz: ");

Serial.println(z_axis);

Buttons

The Esplora comes with an impressive array of buttons. On the left side of the Esplora is an analog joystick and on the right side are digital buttons. The joystick can register the exact x-axis and y-axis position, and also has a center-push button.

To read the joystick inputs, use readJoystickX() and readJoystickY().

xValue = Esplora.readJoystickX();

yValue = Esplora.readJoystickY();

These functions both return an int: Values range from –512 to 512. A return value of zero means that the joystick is in the center and has not been moved. Negative values mean that the joystick is pushed to the left (x) or down (y). Positive values mean that the joystick is pushed to the right (x) or up (y).

To read the center-push button, you can use readJoystickSwitch().

value = Esplora.readJoystickSwitch();

The return value is an int and is either 0 or 1,023. Remember that readJoystickX() and readJoystickY() return 10-bit values and are shifted to make things easier. The center button also returns a 10-bit value but because it is either pushed or not, values returned are extremes. If you need something simpler to use, you can use the readJoystickButton() function.

state = Esplora.readJoystickButton();

This function returns a Boolean: LOW if the button is pressed and HIGH if the button is not pressed.

To read the status of the buttons, there is only one function: readButton().

state = Esplora.readButton(button);

This function takes one parameter, the button that is to be read. The button parameter can be one of four constants: SWITCH_DOWN, SWITCH_LEFT, SWITCH_UP, or SWITCH_RIGHT. This function returns one of two values: HIGH or LOW. A return value of HIGH means the button is in the high position; that is to say, it has not been pressed. A return value of LOW means that the button is in the low position and is currently pressed.

Buzzer

The Arduino Esplora has a buzzer located on the top left of the device that can create simple audio outputs. To create an audio output, use tone().

Esplora.tone(frequency);

Esplora.tone(frequency, duration);

The frequency parameter specifies the audio frequency in hertz, expressed as an unsigned int. The optional duration parameter is the duration of the tone in milliseconds, also expressed as an unsigned int. If omitted, the tone continues until interrupted, either by calling the tone() function with new parameters or by calling the noTone() function.

Esplora.noTone();

This function immediately stops the output of a tone() function.

The tone() and noTone() functions are part of the Arduino language, but these two variants are modified to be used on the Esplora. As such, it is not necessary to specify the pin; the actions are immediately applied to the correct pin.

NOTE

The buzzer is controlled by high-speed PWM, as is the red component of the RGB LED. Using the buzzer may interfere with the red light.

TinkerKit

The Arduino Esplora comes with four TinkerKit connectors; two are inputs and two are outputs.

To read the TinkerKit inputs, use readTinkerkitInputA() and readTinkerkitInputB().

resultA = Esplora.readTinkerkitInputA();

resultB = Esplora.readTinkerkitInputB();

These two functions do not take any parameters and return an int, the value detected on the TinkerKit input. Values range from 0 (0 V) to 1,023 (5 V). There is another way to read TinkerKit inputs, using a single function: readTinkerkitInput().

result = Esplora.readTinkerkitInput(whichInput);

This function takes a parameter, whichInput. This parameter is a Boolean: if it is false (or 0), then the value of TinkerKit input A is returned. If it is true (or 1), then the value of TinkerKit input B is returned.

The Esplora also has two TinkerKit outputs, but currently, there are no Esplora specific functions allowing easy output. However, they are digital outputs just like on any Arduino, so it is still easy to write to their outputs—the trick is to know which output goes where.

There are two outputs: OUT-A and OUT-B. Just below the connector, next to the output identifier, is another piece of information: D3 for Output A and D11 for Output B. These are the reference to the digital outputs, and using digitalWrite(), you can output digital data. These two pins are also capable of PWM, so you can also use analogWrite().

CROSS-REFERENCE

digitalWrite() and analogWrite()are standard functions, which are explained in Chapter 4.

LCD Module

The Arduino Esplora can also host an optional TFT screen placed on the connectors on the middle of the board. This module uses the standard TFT library (as well as SPI), and there are no Esplora-specific functions for this module. However, as everything on the board is hardwired, you don't need as much code to use a screen as other Arduinos. After including the TFT, SPI, and Esplora libraries, all you need to do is reference the Esplora TFT object with EsploraTFT. For more information on the TFT library, see Chapter 13.

There is also another use for the LCD Module connectors. Contrary to most Arduinos, the Esplora does not support shields; apart from the TFT connector, there are no connectors capable of placing a board or shield, and there are no prototyping areas. By using this connector, it is possible to have more inputs and outputs. The connectors on the left side of the Esplora are not electronically connected; they are there solely to fix the TFT screen in place. On the right side, however, several pins are exposed. Of course, this is to allow the TFT screen to talk using the SPI protocol, but there are a few others, for example, to control the backlight. Creating a PCB for use with the Esplora is beyond the scope of this book, but you can find more information on the connector on Arduino's website.

Example Program and Exercises

The Arduino Esplora is an excellent device to get “hands-on,” and the next chapter presents another unique device. The Esplora, in the shape of a handheld game controller, can also be used as a remote control. Without spoiling the next chapter too much, this project converts the Esplora into a remote control for the Arduino Robot, an interesting device that is essentially a moving Arduino. It is controlled by two motors, and can move forward, backwards, and turn around. This sketch will serve as a remote control for the Arduino Robot, by using the two TinkerKit outputs. The left TinkerKit connector controls movement to the left, and the right TinkerKit controls movement to the right. If both are activated, the device goes forward, and if neither is active, then the device stops.

NOTE

If you do not have access to an Arduino Robot, this project can be adapted to other robotic kits. Several interesting devices are available at http://www.robotshop.com/. This can be adapted to both vehicles and robotic arms.

To do this, the sketch sets the TinkerKit outputs to digital mode and constantly monitors the status of the buttons. This sketch will use two TinkerKit outputs: Out A and Out B. Out A will handle the left-hand side motor, and Out B will control the right-hand side motor. To go forward, both motors will be activated at the same time. To turn, only one motor will be activated. The sketch will look like Listing 21.1.

Listing 21.1: Sketch (filename: Chapter21.ino)

1 #include <Esplora.h>

3 #define OUTA 3 // Pin TinkerKit Out A is connected to

4 #define OUTB 11 // Pin TinkerKit Out B is connected to

6 void setup()

7 {

8 pinMode(OUTA, OUTPUT); // TinkerKit A to output

9 pinMode(OUTB, OUTPUT); // TinkerKit B to output

10 }

12 void loop()

13 {

14 boolean outputA = LOW;

15 boolean outputB = LOW;

17 if (Esplora.readButton(SWITCH_UP) == LOW)

18 outputA = outputB = HIGH;

20 if (Esplora.readButton(SWITCH_LEFT) == LOW)

21 outputB = HIGH;

23 if (Esplora.readButton(SWITCH_RIGHT) == LOW)

24 outputA = HIGH;

26 digitalWrite(OUTA, outputA);

27 digitalWrite(OUTB, outputB);

28 }

On line 1, the Esplora library is imported, the first thing needed for this project. On lines 3 and 4, there are some define directives, which define the digital pins used on the TinkerKit outputs because there are no functions available to write to the TinkerKit pins directly. Because you have to do this the old way, it requires pinMode() calls in setup(). This is done on line 8 and 9; both pins are set to OUTPUT.

loop()is declared on line 12, and this is where the buttons will be read and, if necessary, the outputs will be written to. It starts on line 14 with the creation of two variables: outputA and outputB. As you can imagine, they will be used to hold the output status. They are defined as LOW by default, meaning that without any modification, they will set the outputs LOW. On line 17, the first button read is made. If the up button is pressed, both outputA and outputB are set high.

The second read, on line 20, checks to see if the left button has been pressed. If it has, then outputB is set HIGH. If the user is also pressing on the up button, the sketch changes the output to HIGH anyway. This is why the variables were initially set to LOW: Reads are made to see if there is a reason to set the variable to HIGH. If two or more conditions update the variable, that isn't a problem; the end result is the same. A third read is made on line 23 to see if the right button has been pressed.

Finally, the two digital outputs are updated with the contents of the variables. loop()then repeats.

A simple sketch can turn an advanced device into a remote control, even if there are no specific TinkerKit output routines. By making the sketch use the digital outputs instead of using specific functions, you can perform more software actions than the library alone allows. The TinkerKit outputs can be used as digital output or PWM, but by knowing the exact pin number, you could use these pins as serial outputs, or for other purposes.

The output of this sketch is binary only; either the outputs are on or off. With a little bit of adjustment, this could quickly become an analog output, using the joystick. That will require a little bit of modification to the example in the next chapter as well, but you will get to that later.

You will have a remote control allowing a new device freedom of movement, but there is one button that is not used, the down button. There is no point using it to slow down, so why not use it to make beep noises? Just like a car horn, warning the cat or dog to get out of the way.

Alternatively, for advanced programmers, use the Esplora's accelerometer to control output.

Summary

In this chapter you have seen the Arduino Esplora, an interesting device with lots of embedded electronics and a rich library to read and write the components. You have seen the library and the different functions used to read from and write to the different components. You have seen how easy it is to create a project. In the next chapter, you will see the Arduino Robot and the library used to control it, and you will be able to use the sketch presented in the chapter to control its movement.