Introduction

Note: This section is still under construction with many updates and improvements in the pipeline.

BLEduino 101

The BLEduino is a highly versatile and friendly BLE (Bluetooth 4.0) development board. It’s Arduino-compatible, very tiny, and compatible with most Arduino shields (via the Shield-Shield). The BLEduino is programmed using the standard Arduino IDE and includes a BLE Library that enables you to easily send and receive data wirelessly. Additionally, the BLEduino comes with a powerful iOS app. The app allows you to communicate and control your BLEduino via “modules” within the app. Each module represents a discrete functionality you can play with and is accompanied by a matching Arduino sketch.

Pro tip

If you’re new to Arduino or Arduino programming, we recommend you check out the official Arduino website which covers a lot of the basics. The Arduino forum and language reference are also extremely useful.

Shield-Shield 101

The Shield-Shield is a BLEduino expansion board that allows you to use your BLEduino with most Arduino Shields. It adapts the BLEduino’s pin layout to match that of an Arduino Leonardo.

The Shield-Shield also accounts for differences in Arduino board revisions by including a small mechanical switch on the lower right. The switch allows you to move the I2C pins from their current location (compatible with modern shields) to their older location (compatible with older shields).

Pro tip

Not sure if your shield is based on the old Arduino board layout or the new layout? Not a problem. A trick we usually use is to look at the top left pins on your shield, assuming the same orientation above. If you see the SCL or SDA pins up there, your board is based on the new format (you can leave the switch set to A4 and A5). If you don't see the SCL or SDA pins, it may be based on the old format. Fundamentally, what you're looking for is whether your shield uses I2C or not, and if it does, where it expects to "find" those pins. If it's based on the new layout, it'll look for those pins on the top left. If based on the old layout, it'll look for them on the bottom right (where A5 and A4 currently are).

Installing the Arduino IDE

To program the BLEduino, you’ll need the latest non-beta (1.0.5), Arduino development environment. You can download the Arduino IDE here. Note that the BLEduino isn't fully compatible with the beta Arduino IDE (1.5.7).

Pro tip

Want a rundown on the Arduino IDE? Not a problem. The Arduino site has a great guide.

Installing the BLEduino Drivers

Note: You'll need a BLEduino and a USB Micro B cable for this part.

The next thing you'll need to do is install the proper BLEduino drivers. This process is Plug and Play on Mac OS and Linux but slightly more complicated on Windows.

Mac

The first time you plug in the BLEduino on Mac, the "Keyboard Setup Assistant" will launch. This is due to the OS thinking the BLEduino is a keyboard (which technically, it could be). There's nothing to configure, so you can close this dialogue by clicking the red button in the top left of the window. Success!

Linux

Just plug and play. Nothing to do here!

Windows

The following instructions are for Windows 7 (and XP with slight variations) only.
If you are using Windows 8, your instructions can be found here.

First, download and extract this zip somewhere easy to access, like your desktop.

Second, plug in your board and wait for Windows to begin its driver installation process. If the installer does not launch automatically, you'll have to navigate to the Windows Device Manager and find the BLEduino (USB IO Board) listing manually.

Choose "Browse my computer for driver software", and click Next.

Click the "Browse..." button. Navigate to the extracted BLEduino driver folder you downloaded. Click OK, then click Next.

Windows will try to install the driver but will complain about the driver being unsigned. It’s safe to select ‘Install this driver software anyway’ on the warning dialog.

The Driver is installed! Note the COM port used at the top. (In this case it's COM 3) This will be useful when uploading code to the BLEduino.

BLEduino in Board list.

Note: You'll need to download this zip folder for this part.

To get the IDE to recognize the BLEduino and properly upload code to it, you need to tell the IDE that the board you’ll be programming is a BLEduino. However, if you try to pick the BLEduino from the board list, you'll find it's not there.

To add the BLEduino to the list, download the zip folder mentioned at the beginning of this section and put it inside your Arduino sketchbook. The Arduino sketchbook is usually found in your home directory (Documents in Windows). To double check, you can go to File > Preferences within the Arduino IDE and check the Sketchbook location text box. With this location you simply just drop the unzipped Hardware folder into the Arduino folder.

Now, when you open the Arduino IDE, you should see the BLEduino inside the board list.

Using the BLEduino Library

Note: You'll need to download the BLEduino library for this part.

The BLEduino comes with a BLE library that allows you to easily send and receive data via BLE. The BLEduino can still be programmed without the library but it won’t be able to use its BLE functionalities without it. Importing the library and examples is fairly straightforward. You first download the library. Then you import it into Arduino via Sketch > Import Library > Add Library. If you have any doubts, the following guide will help.

Get the app

Note: The iOS app is currently going through the app store review process. Unfortunately, the only way to run it on your phone is using one of the following two methods. They aren't as straight forward as the app store, but they get the job done. The app should be on the app store by next week.

Hello World!

After doing all of the previous steps there's only one thing left. Get hacking! Copy / Paste the following code into the Arduino IDE and hit upload (make sure the BLEduino is selected on the board list). This code allows you to send messages between the BLEduino and the Phone via the Console module.

//Console Module Code
//Write and receive character strings
#include <BLEduino.h>;

BLEduino BLE;

void setup(){
  BLE.begin(); //Initialize BLE object
  BLE.sendCommand(COMMAND_RESET); //Start advertising BLEduino

  Serial.begin(57600);

  while(!Serial){;} //Wait for serial monitor to be opened 

  Serial.println("Console Test.  Write a message (up to 20 characters long) and press enter...");
}

void loop(){
  
  //Read message from BLEduino
  //Print in Serial Monitor
  if(BLE.available()){
    
    //Read packet
    BLEPacket packet = BLE.read();
    
    //Parse packet
    uint8_t length = packet.length;
    uint8_t * data = packet.data;
    
    /*-------------------------------------------------
    Packet Structure for Keyboard data
    ||      0      |      1      | ... |      N      ||
    || Character 0 | Character 1 | ... | Character N ||
    --------------------------------------------------*/
    
    //Print each character
    for(int i = 0; i < length; i++){
      Serial.print((char)data[i]);
    }

    Serial.println(""); //Add new line.

  }
  
  //Send message to BLEduino
  if(Serial.available()){
    
    if(!check_size()){
      return;
    }

    byte length = Serial.available();
    byte message[20];

    for(int i = 0; i < length; i++){
      message[i] = Serial.read();
    }

    BLE.sendData(UART_SEND, message, length);

    Serial.println("Message Sent");
  }
}

bool check_size(){
  if(Serial.available() > 20){
    Serial.flush();

    Serial.println("Message can be 20 characters max.");
    
    return 0;
  }
  return 1;
}

            

With this code uploaded you can now open the "Console" module on the app and send messages bettween the app and the BLEduino (via the Serial Monitor).

BLEduino side

Phone side

Next steps

Check out our other examples.