Note: this page refers to a product that is retired.

Esplora Library

A library for using the Esplora board.

Overview

This library is archived and is no longer being maintained. It can be still be downloaded and used, but is read-only and cannot be contributed to. For more information, you can view this repository on GitHub.

The Arduino Esplora has a set of functions for easily interfacing with the sensors and actuators mounted on the board. The functions are accessible through the Esplora class.

The library offers easy access to the data from the onboard sensors, and provides the ability to change the state of the outputs.

The sensors available on the board are:

  • 2-Axis analog joystick
  • center push-button of the joystick
  • 4 push-buttons
  • microphone
  • light sensor
  • temperature sensor
  • 3-axis accelerometer
  • 2 TinkerKit input connectors

The actuators available on the board are:

  • bright RGB (Red-Green-Blue) LED
  • piezo buzzer
  • 2 TinkerKit output connectors

For more information about the Esplora, visit the Esplora documentation.

NOTE: If you're using the Arduino IDE version 1.0.3 or earlier , you will need to download the latest version of this library, or get it from the Arduino GitHub repository.

To use this library

1#include <Esplora.h>

Examples

The Esplora Beginners examples show the functionality of the inputs and outputs of the board. They are a good place to start experimenting with the Esplora's capabilities. The Expert examples are more detailed sketches that illustrate project ideas that utilize the board features in novel ways.

Beginners

Experts

  • EsploraKart : Use the Esplora as a controller to play a kart racing game.
  • EsploraTable : Print the Esplora sensor information to a table format.
  • EsploraRemote : Connect the Esplora to Processing and control the outputs.
  • EsploraPong : Play Pong with the Esplora using Processing.

Functions


Esplora constructor

Description

Esplora is the base class for all methods used by the board. It is not called directly, but invoked whenever you use a function that relies on it.


readSlider()

Description

Reads the value from the linear potentiometer as a 10-bit number. This means that it will map input voltages between 0 and 5 volts into integer values between 0 and 1023. This yields a resolution between readings of: 5 volts / 1024 units or, .0049 volts (4.9 mV) per unit.

Syntax

1Esplora.readSlider()

Parameters

none

Returns

int : The linear potentiometer's position, mapped to a value between 0 and 1023.

Example

1#include <Esplora.h>
2
3void setup()
4{
5 Serial.begin(9600);
6}
7
8void loop()
9{
10 int value = Esplora.readSlider();
11 Serial.println(value);
12
13 delay(1000);
14}

readLightSensor()

Description

Reads the intensity of light hitting the light sensor as a 10-bit number. This means that it will map input voltages between 0 and 5 volts into integer values between 0 and 1023. This yields a resolution between readings of: 5 volts / 1024 units or, .0049 volts (4.9 mV) per unit.

Syntax

1Esplora.readLightSensor()

Parameters

none

Returns

int : The amount of light hitting the sensor, mapped to a value between 0 and 1023.

Example

1#include <Esplora.h>
2
3void setup()
4{
5 Serial.begin(9600);
6}
7
8void loop()
9{
10 int value = Esplora.readLightSensor();
11 Serial.println(value);
12
13 delay(1000);
14}

readTemperature()

Description

Reads the ambient temperature of the temperature sensor and returns a reading in either the Celsius or Fahrenheit scale, depending on the parameter passed.

Syntax

1readTemperature(scale)

Parameters

scale: the scale of the output, valid arguments are: DEGREES_C and DEGREES_F

Returns

int : The temperature reading in Celsius or Fahrenheit. The Celsius range is from -40°C to 150°C, the Fahrenheit range is from -40°F to 302°F.

Example

1#include <Esplora.h>
2
3void setup()
4{
5 Serial.begin(9600);
6}
7
8void loop()
9{
10 int celsius = Esplora.readTemperature(DEGREES_C);
11 int fahrenheit = Esplora.readTemperature(DEGREES_F);
12 Serial.print(celsius);
13 Serial.print("\t");
14 Serial.print(fahrenheit);
15
16 delay(1000);
17}

readMicrophone()

Description

Read the amplitude from the microphone. It returns a valure between 0 and 1023.

Syntax

1readMicrophone()

Parameters

none

Returns

int : The amplitude mapped to a range of 0 to 1023.

Example

1#include <Esplora.h>
2
3void setup()
4{
5 Serial.begin(9600);
6}
7
8void loop()
9{
10 int value = Esplora.readMicrophone();
11 Serial.println(value);
12
13 delay(1000);
14}

readJoystickSwitch()

Description

Reads the joystick's button and returns if its state is 0 or 1023. If you prefer something more consistent with the readButton() function, you may want to use readJoystickButton() instead. That function does the same as this, but returns LOW when the joystick button is pressed, and HIGH when not pressed.

Syntax

1Esplora.readJoystickSwitch()

Parameters

none

Returns

0 when pressed, 1023 when not pressed.

Example

1#include <Esplora.h>
2
3
4void setup(){
5 // nothing in setup
6}
7
8void loop()
9{
10 int button = Esplora.readJoystickSwitch();
11
12 if(button == 0)
13 {
14 Esplora.writeRed(255);
15 }
16 else {
17 Esplora.writeRed(0);
18 }
19}

readJoystickButton()

Description

Reads the joystick's button and returns if its state is LOW or HIGH. This function does basically the same thing as readJoystickSwitch(), but it returns values consistent with the readButton() function.

Syntax

1Esplora.readJoystickButton()

Parameters

none

Returns

LOW when pressed, HIGH when not pressed.

Example

1#include <Esplora.h>
2
3
4void setup(){
5 // nothing in setup
6}
7
8void loop()
9{
10 int button = Esplora.readJoystickButton();
11
12 if(button == LOW)
13 {
14 Esplora.writeRed(255);
15 }
16 else {
17 Esplora.writeRed(0);
18 }
19}

readAccelerometer()

Description

Reads values from the Esplora's accelerometer. Each of the three axes are accessed independently.

Syntax

1Esplora.readAccelerometer(axis)

Parameters

axis : char, determines what axis to read.

  • X_AXIS to read the X-axis value
  • Y_AXIS to read the Y-axis value
  • Z_AXIS to read the Z-axis value

Returns

int : the value of the readings on the chosen axis. The accelerometer returns zero when it is perpendicular to the direction of gravity. Positive or negative values result when it is accelerates in one of the two directions of the axis.

Example

1#include <Esplora.h>
2
3void setup()
4{
5 Serial.begin(9600);
6}
7
8void loop()
9{
10 int x_axis = Esplora.readAccelerometer(X_AXIS);
11 int y_axis = Esplora.readAccelerometer(Y_AXIS);
12 int z_axis = Esplora.readAccelerometer(Z_AXIS);
13
14 Serial.print("x: ");
15 Serial.print(x_axis);
16 Serial.print("\ty: ");
17 Serial.print(y_axis);
18 Serial.print("\tz: ");
19 Serial.println(z_axis);
20
21 delay(500);
22}

readButton()

Description

Reads a button's state and returns if it is HIGH or LOW.

Syntax

1Esplora.readButton(button)

Parameters

button: the associated button that you wanto read. Valid argument are:

  • SWITCH_1 or SWITCH_DOWN
  • SWITCH_2 or SWITCH_LEFT
  • SWITCH_3 or SWITCH_UP
  • SWITCH_4 or SWITCH_RIGHT
  • JOYSTICK_DOWN = JOYSTICK_BASE
  • JOYSTICK_LEFT = JOYSTICK_BASE+1
  • JOYSTICK_UP = JOYSTICK_BASE+2
  • JOYSTICK_RIGHT = JOYSTICK_BASE+3

Returns

LOW when pressed, HIGH when not pressed.

Example

1#include <Esplora.h>
2
3void setup(){}
4
5void loop()
6{
7int button = Esplora.readButton(SWITCH_DOWN);
8
9if(button == LOW)
10 {
11 Esplora.writeRed(255);
12 }
13else {
14 Esplora.writeRed(0);
15 }
16}

readJoystickX()

Description

Read the position of the X-axis of the joystick. When the joystick is in the center, it returns zero. Positive values indicate the joystick has moved to the right and negative values when moved to the left.

Syntax

1Esplora.readJoystickX()

Parameters

none

Returns

int : 0 when the joystick is in the middle of the x-axis; 1 to 512 when the joystick is moved to the right; -1 to -512 when the joystick is moved to the left.

Example

1#include <Esplora.h>
2
3void setup()
4{
5Serial.begin(9600);
6}
7
8void loop()
9{
10int value = Esplora.readJoystickX();
11Serial.println(value);
12
13delay(1000);
14}

readJoystickY()

Description

Read the position of the Y-axis of the joystick. When the joystick is in the center, it returns zero. Positive values indicate the joystick has moved up and negative values when moved down.

Syntax

1Esplora.readJoystickY()

Parameters

none

Returns

int : 0 when the joystick is in the middle of the y-axis; 1 to 512 when the joystick is moved up; -1 to -512 when the joystick is moved down.

Example

1#include <Esplora.h>
2
3void setup()
4{
5Serial.begin(9600);
6}
7
8void loop()
9{
10int value = Esplora.readJoystickY();
11Serial.println(value);
12
13delay(1000);
14}

writeRGB()

Description

Write values representing brightness to the RGB LED. By mixing different values, it's possible to create different color combinations.

Syntax

1Esplora.writeRGB(red, green, blue)

Parameters

  • red: int, value is to set the red LED brightness. Range 0 to 255
  • green: int, value is to set the green LED brightness. Range 0 to 255
  • blue: int, value is to set the blue LED brightness. Range 0 to 255

Returns

nothing

Example

1#include <Esplora.h>
2
3void setup() {}
4
5void loop()
6{
7 Esplora.writeRGB(0, 128, 255);
8 delay(1000);
9 Esplora.writeRGB(255, 0, 128);
10 delay(1000);
11 Esplora.writeRGB(128, 255, 0);
12 delay(1000);
13}

writeRed()

Description

Write values to the red LED that correspond to the brightness.

Syntax

1Esplora.writeRed(value)

Parameters

value: int, value to set the red LED brightness. Range 0 to 255

Returns

nothing

Example

1#include <Esplora.h>
2
3void setup() {}
4
5void loop()
6{
7 for(int i=0; i<256; i++)
8 {
9 Esplora.writeRed(i);
10 delay(100);
11 }
12}

writeGreen()

Description

Write values to the green LED that correspond to the brightness.

Syntax

1Esplora.writeGreen(value)

Parameters

value: int, value to set the green LED brightness. Range 0 to 255

Returns

nothing

Example

1#include <Esplora.h>
2
3void setup() {}
4
5void loop()
6{
7 for(int i=0; i<256; i++)
8 {
9 Esplora.writeGreen(i);
10 delay(100);
11 }
12}

writeBlue()

Description

Write values to the blue LED that correspond to the brightness.

Syntax

1Esplora.writeBlue(value)

Parameters

value: int, value to set the blue LED brightness. Range 0 to 255

Returns

nothing

Example

1#include <Esplora.h>
2
3void setup() {}
4
5void loop()
6{
7 for(int i=0; i<256; i++)
8 {
9 Esplora.writeBlue(i);
10 delay(100);
11 }
12}

readRed()

Description

Read the brightness value of the red LED.

Syntax

1Esplora.readRed()

Parameters

none

Returns

int : the brightness of the red LED between 0 and 255.

Example

1#include <Esplora.h>
2
3void setup()
4{
5 Serial.begin(9600);
6}
7
8void loop()
9{
10 int dimmerValue = Esplora.readSlider();
11 Esplora.writeRed(dimmerValue);
12 Serial.println(Esplora.readRed());
13
14 delay(500);
15}

readGreen()

Description

Read the brightness value of the green LED.

Syntax

1Esplora.readGreen()

Parameters

none

Returns

int : the brightness of the green LED between 0 and 255.

Example

1#include <Esplora.h>
2
3void setup()
4{
5 Serial.begin(9600);
6}
7
8void loop()
9{
10 int dimmerValue = Esplora.readSlider();
11 Esplora.writeGreen(dimmerValue);
12 Serial.println(Esplora.readGreen());
13
14 delay(500);
15}

readBlue()

Description

Read the brightness value of the blue LED.

Syntax

1Esplora.readBlue()

Parameters

none

Returns

int : the brightness of the blue LED between 0 and 255.

Example

1#include <Esplora.h>
2
3void setup()
4{
5 Serial.begin(9600);
6}
7
8void loop()
9{
10 int dimmerValue = Esplora.readSlider();
11 Esplora.writeBlue(dimmerValue);
12 Serial.println(Esplora.readBlue());
13
14 delay(500);
15}

tone()

Description

Generates a square wave of the specified frequency from the Esplora's onboard buzzer. A duration can be specified in milliseconds, otherwise the wave continues until a call to Esplora.noTone().

Only one tone can be generated at a time. If a tone is already playing, the call will set its frequency.

Use of the tone() function will interfere with fading the red LED.

Syntax

1Esplora.tone(frequency, duration)

Parameters

frequency: the frequency of the tone in hertz - unsigned int

duration: the duration of the tone in milliseconds (optional) - unsigned long

Returns

nothing


noTone()

Description

Stops the generation of a square wave triggered by Esplora.tone(). Has no effect if no tone is being generated.

Syntax

1Esplora.noTone()

Parameters

none

Returns

nothing

Suggest changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.

License

The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.