Arduino

This tutorial guides you through all the steps required for setting up the Arduino hardware and software and using our CommonSense Arduino library.

Hardware and software requirements

For this tutorial we will need the following things:

Either

OR

For both compositions we also need:

  • A CommonSense account - available for free here
  • Breadboard
  • Breadboard wires
  • Diffused bright LED
  • At least a 220Ω resistor
  • Ethernet cable
  • Working ethernet connection

Software installation

Visit the Arduino website to download the latest Arduino integrated development environment (IDE) software for your platform. (At the time of writing 1.0.5 tested successfully)

Install the IDE and the drivers necessary for your USB Serial adapter if you're using one.
Complete installation guides are available for: Windows, OS X and Linux.

Head over to the Github library page and download our library using the Download ZIP button on the right side of the page.

The Arduino IDE has a built-in function for installing libraries.
Download the library as a zip file and extract it. Rename the resulting 'commonsense-arduino-lib-master' folder to 'CommonSense'.
Go to Sketch > Import Library... > Add Library... and select the folder containing the library.

Hardware setup

We start by making sure the Arduino and Ethernet Shield work.

  • Connect the Arduino to your computer using the USB cable.
    If the LED with 'L' written next to it lights up, it should be okay.

  • Place the Ethernet Shield on top of the arduino, making sure that the pins are properly seated.
    The 'ON' LED of the Ethernet Shield should also be lighting up now.
    Connecting an ethernet cable will make the 'LINK' LED light up if there's communication going on.

  • Connect the the LED in a similar fashion to the following diagrams:

arduino_bb

arduino_schem
Images made using Fritzing

This concludes the hardware setup.

Testing the hardware

Open the 'Blink' example by going to File > Examples > 01.Basics > Blink

Note: The pin used in this example is 13, because that pin has a LED attached to it on most Arduino boards. Keep in mind that pins 10 through 13 are used by the Ethernet Shield itself and should not be used.
If you're planning on using more shields in the future, make sure that the shields don't require the same pins.

We are going to change the line int led = 13; to int led = 2;.
By avoiding the use of pin 13, we can prevent the LED and Ethernet Shield from interfering with each other.

Use the verify button in the top-left corner to see if the code compiles correctly.

If all's well, you should get a message like this: ide_done_compiling

Upload the example we just edited using the upload button in the top-left corner. Using the upload button will also verify your code again.
Once it's done uploading, you will get a message similar to uploading and the LED should turn on and off.

Writing a sketch

Before we start programming, let's take a look at what a sketch is. A sketch is the Arduino name for a program. It is also however a simplified C/C++ program. The Arduino IDE takes of some things in the background so all you need to do in your sketch is create a setup() and loop() function.

The setup() function can be used to setup variables and do things like starting serial communication with your computer.

The loop() function is used to control your arduino after the initial setup.
The loop() function keeps repeating itself when it's done so your program can respond to any changes (e.g. buttons being pushed) in each iteration of the loop.

Let's get started with our sketch by creating a new one in the IDE: Go to File > New.

We now got a blank sketch which we're going to use for our sketch.

Start by including the CommonSense library and its dependencies:

#include <SPI.h> // Library used by the CommonSense library
#include <Ethernet.h> // Library used by the CommonSense library 
#include <CommonSense.h> // Our library itself

This makes sure we have access to the things we need from the CommonSense library.

Say our username is 'user', our password is 'password' and we're using an Arduino Uno.
We will now need to store some information that's required for authenticating ourselves on CommonSense.
We will need the MD5 hash of our password. There are several tools online which can be used to get the hash of a password.
We will need a MAC address to get access to internet using DHCP.
Your MAC address can be found on a sticker underneath the Ethernet Shield or Board.
Let's pretend ours is AA-BB-CC-DD-EE-FF.

const char *username = "user"; // your CommonSense username
const char *password = "5f4dcc3b5aa765d61d8327deb882cf99"; // MD5 hash of your password
const byte MAC[] = { 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF }; //mac address used to setup ethernet

Now we're going to create an object which we can use to talk to CommonSense.

CommonSense sense = CommonSense(username, password, MAC); // object we use to talk to commonsense

When we're creating a sensor in CommonSense, the server will return us the identifier for that sensor.
We're storing the sensor id and pin belonging to it in EEPROM so the data is saved between sketches.
To do this we will have to create a way to access the EEPROM:

long sensors[10]; // array containing the pin and its sensor id
int sensorsSize = sizeof(sensors) / sizeof(sensors[0]); // the amount of elements in sensors[]
long EEMEM dataInEEPROM[sizeof(sensors) / sizeof(sensors[0])]; // allocate space in EEPROM for an array the size of sensors[]

int ledPin = 2; // store the pin our led is connected to

All the variables we need are now set. We can now start writing the setup() function. We will have to do 4 things in this function:

  • Start serial communication so the Arduino can print messages for us to read.
  • Print a serial message to let us know that the Arduino works.
  • Set the LED pin to OUTPUT so we can provide the LED with current.
  • Set sense.debug to show us brief information.
  • Call the begin() function to setup ethernet, time and log on to CommonSense.
  • Create a sensor on CommonSense and store the identifier so we can start uploading data.
void setup() {              
    Serial.begin(9600); // Sets the data rate for transmission to 9600 bits per second (baud)
    Serial.println(F("Hello world!")); //Let us know that we're alive
    pinMode(ledPin, OUTPUT); // set the pin to OUTPUT so it can provide current to the LED.

    sense.debug = 1; // turn on serial output

    sense.begin(); // This will configure ethernet and time. When that's done it'll log us onto CommonSense.

    sense.loadSensorsFromEEPROM(sensors, sensorsSize); // load data from EEPROM into sensors[]

    sense.createSensor("BlinkingLight", "LED", "arduinoled", -1, sensors, sensorsSize); // create a sensor on commonsense
}

In the loop() we will:

  • Print the time
  • Keep checking what the latest data value of our sensor was and light up the LED accordingly.

If the latest value was 0, we will upload 1 and turn on the light. If this is not the case we upload 0 and turn off the light again.
We can use a counter to prevent exceeding our account request limit.

int count = 0; // counter to prevent hitting our request limit
void loop() {
    Serial.print(F("\nTime: "));
    Serial.println(sense.time()); //get the current time and print it

    int lastData = sense.getLastData(sensors[0]); // get the last data from sensors[0]
    if(0 == lastData){
        digitalWrite(ledPin, HIGH);
        sense.uploadData(sensors[0], 1, sense.time());
    }else{
        digitalWrite(ledPin, LOW);
        sense.uploadData(sensors[0], 0, sense.time());
    }    

    count++; // increment the counter

    if(count == 10)
        while(true) ; // do nothing

    delay(1000); //wait 1 second before going through the loop again
}

This concludes writing the sketch.

Upload the sketch to the Arduino and open the serial monitor by clicking on the button in the top right corner.
Reset the Arduino using the button on top of the Ethernet Shield or Board so you don't miss any messages.
If you're seeing garbage characters, make sure the baud is set to 9600 in the bottom right corner.

More learning resources

The following pages can be useful if you would like to learn more about what's possible with Arduino.