Bluetooth Low Energy is the hottest new low-power, 2.4GHz spectrum wireless protocol. In particular, its the only wireless protocol that you can use with iOS without needing special certification and it's supported by all modern smart phones. This makes it excellent for use in portable projects that will make use of an iOS or Android phone or tablet. It also is supported in Mac OS X and Windows 8+

At the Feather M0's heart is an ATSAMD21G18 ARM Cortex M0 processor, clocked at 48 MHz and at 3.3V logic, the same one used in the new Arduino Zero. This chip has a whopping 256K of FLASH (8x more than the Atmega328 or 32u4) and 32K of RAM (16x as much)! This chip comes with built in USB so it has USB-to-Serial program & debug capability built in with no need for an FTDI-like chip.

To make it easy to use for portable projects, we added a connector for any of our 3.7V Lithium polymer batteries and built in battery charging. You don't need a battery, it will run just fine straight from the micro USB connector. But, if you do have a battery, you can take it on the go, then plug in the USB to recharge. The Feather will automatically switch over to USB power when its available. We also tied the battery thru a divider to an analog pin, so you can measure and monitor the battery voltage to detect when you need a recharge.

The Bluefruit LE module is an nRF51822 chipset from Nordic, programmed with multi-function code that can do quite a lot! For most people, they'll be very happy to use the standard Nordic UART RX/TX connection profile. In this profile, the Bluefruit acts as a data pipe, that can 'transparently' transmit back and forth from your iOS or Android device. You can use our iOS App or Android App, or write your own to communicate with the UART service.

The board is capable of much more than just sending strings over the air! Thanks to an easy to learn AT command set, you have full control over how the device behaves, including the ability to define and manipulate your own GATT Services and Characteristics, or change the way that the device advertises itself for other Bluetooth Low Energy devices to see. You can also use the AT commands to query the die temperature, check the battery voltage, and more, check the connection RSSI or MAC address, and tons more. Really, way too long to list here!

Comes fully assembled and tested, with a USB bootloader that lets you quickly use it with the Arduino IDE. We also toss in some header so you can solder it in and plug into a solderless breadboard. Lipoly battery, breadboard and USB cable not included (but we do have lots of options in the shop if you'd like!)

#20 / SDA - GPIO #20, also the I2C (Wire) data pin. There's no pull up on this pin by default so when using with I2C, you may need a 2.2K-10K pullup.

#21 / SCL - GPIO #21, also the I2C (Wire) clock pin. There's no pull up on this pin by default so when using with I2C, you may need a 2.2K-10K pullup.

#5 - GPIO #5

#6 - GPIO #6

#9 - GPIO #9, also analog input A7. This analog input is connected to a voltage divider for the lipoly battery so be aware that this pin naturally 'sits' at around 2VDC due to the resistor divider

#10 - GPIO #10

#11 - GPIO #11

#12 - GPIO #12

#13 - GPIO #13 and is connected to the red LED next to the USB jack

A0 - This pin is analog inputA0 but is also an analog output due to having a DAC (digital-to-analog converter). You can set the raw voltage to anything from 0 to 3.3V, unlike PWM outputs this is a true analog output

A1 thru A5 - These are each analog input as well as digital I/O pins.

SCK/MOSI/MISO (GPIO 24/23/22)- These are the hardware SPI pins, you can use them as everyday GPIO pins (but recommend keeping them free as they are best used for hardware SPI connections for high speed and are shared with the BLE)

Bluefruit LE Module + Indicator LEDs

Since not all pins can be brought out to breakouts, due to the small size of the Feather, we use these to control the BLE module

#8 - used as the Bluefruit CS (chip select) pin

#7 - used as the Bluefruit IRQ (interrupt request) pin.

#4 - used as the Bluefruit Reset pin

Since these are not brought out there should be no risk of using them by accident!

Other Pins!

RST - this is the Reset pin, tie to ground to manually reset the ATSAMD, as well as launch the bootloader manually

ARef - the analog reference pin. Normally the reference voltage is the same as the chip logic voltage (3.3V) but if you need an alternative analog reference, connect it to this pin and select the external AREF in your firmware. Can't go higher than 3.3V!

DFU - this is the force-DFU (device firmware upgrade) pin for over-the-air updates to the Bluefruit module. You probably don't need to use this but its available if you need to upgrade! Check out the DFU Bluefruit Upgrades page for how to use it. Otherwise, keep it disconnected.

SWD Pins

There's two sets of SWD pins. These are used for program/debug of the two processors on the Feather.

The round pads on the right are for the ATSAMD21G18 (main processor). The rectangular pads to the left are for the nrf51822 inside the BLE module.

You cannot connect these together to debug both at the same time!

Factory Reset

The (somewhat deceptively labeled) 'Reset' pad on the bottom of the PCB beside SWCLK and SWDIO is for Factory Reset. Connecting this pad to GND at startup will perform a factory reset, erasing any config settings and may be useful trying to recover a device in a faulty state. Be sure to remove the connection to GND after the first power cycle.

Assembly

We ship Feathers fully tested but without headers attached - this gives you the most flexibility on choosing how to use and configure your Feather

Header Options!

Before you go gung-ho on soldering, there's a few options to consider!

The first option is soldering in plain male headers, this lets you plug in the Feather into a solderless breadboard

Another option is to go with socket female headers. This won't let you plug the Feather into a breadboard but it will let you attach featherwings very easily

We also have 'slim' versions of the female headers, that are a little shorter and give a more compact shape

Finally, there's the "Stacking Header" option. This one is sort of the best-of-both-worlds. You get the ability to plug into a solderless breadboard and plug a featherwing on top. But its a little bulky

Soldering in Plain Headers

Prepare the header strip:

Cut the strip to length if necessary. It will be easier to solder if you insert it into a breadboard - long pins down

Add the breakout board:

Place the breakout board over the pins so that the short pins poke through the breakout pads

Power Management

Battery + USB Power

We wanted to make the Feather easy to power both when connected to a computer as well as via battery. There's two ways to power a Feather. You can connect with a MicroUSB cable (just plug into the jack) and the Feather will regulate the 5V USB down to 3.3V. You can also connect a 4.2/3.7V Lithium Polymer (Lipo/Lipoly) or Lithium Ion (LiIon) battery to the JST jack. This will let the Feather run on a rechargable battery. When the USB power is powered, it will automatically switch over to USB for power, as well as start charging the battery (if attached) at 100mA. This happens 'hotswap' style so you can always keep the Lipoly connected as a 'backup' power that will only get used when USB power is lost.

The above shows the Micro USB jack (left), Lipoly JST jack (top left), as well as the 3.3V regulator and changeover diode (just to the right of the JST jack) and the Lipoly charging circuitry (to the right of the Reset button). There's also a CHG LED, which will light up while the battery is charging. This LED might also flicker if the battery is not connected.

Power supplies

You have a lot of power supply options here! We bring out the BAT pin, which is tied to the lipoly JST connector, as well as USB which is the +5V from USB if connected. We also have the 3V pin which has the output from the 3.3V regulator. We use a 500mA peak regulator. While you can get 500mA from it, you can't do it continuously from 5V as it will overheat the regulator. It's fine for, say, powering an ESP8266 WiFi chip or XBee radio though, since the current draw is 'spikey' & sporadic.

Measuring Battery

If you're running off of a battery, chances are you wanna know what the voltage is at! That way you can tell when the battery needs recharging. Lipoly batteries are 'maxed out' at 4.2V and stick around 3.7V for much of the battery life, then slowly sink down to 3.2V or so before the protection circuitry cuts it off. By measuring the voltage you can quickly tell when you're heading below 3.7V

To make this easy we stuck a double-100K resistor divider on the BAT pin, and connected it to D9 (a.k.a analog #7 A7). You can read this pin's voltage, then double it, to get the battery voltage.

This voltage will 'float' at 4.2V when no battery is plugged in, due to the lipoly charger output, so its not a good way to detect if a battery is plugged in or not (there is no simple way to detect if a battery is plugged in)

ENable pin

If you'd like to turn off the 3.3V regulator, you can do that with the EN(able) pin. Simply tie this pin to Ground and it will disable the 3V regulator. The BAT and USB pins will still be powered

Alternative Power Options

The two primary ways for powering a feather are a 3.7/4.2V LiPo battery plugged into the JST port or a USB power cable.

If you need other ways to power the Feather, here's what we recommend:

Do not use alkaline or NiMH batteries and connect to the battery port - this will destroy the LiPoly charger and there's no way to disable the charger

Do not use 7.4V RC batteries on the battery port - this will destroy the board

The Feather is not designed for external power supplies - this is a design decision to make the board compact and low cost. It is not recommended, but technically possible:

Connect an external 3.3V power supply to the 3V and GND pins. Not recommended, this may cause unexpected behavior and the EN pin will no longer. Also this doesn't provide power on BAT or USB and some Feathers/Wings use those pins for high current usages. You may end up damaging your Feather.

Connect an external 5V power supply to the USB and GND pins. Not recommended, this may cause unexpected behavior when plugging in the USB port because you will be back-powering the USB port, which could confuse or damage your computer.

Arduino IDE Setup

After you have downloaded and installed the latest version of Arduino IDE, you will need to start the IDE and navigate to the Preferences menu. You can access it from the File menu in Windows or Linux, or the Arduino menu on OS X.

A dialog will pop up just like the one shown below.

We will be adding a URL to the new Additional Boards Manager URLs option. The list of URLs is comma separated, and you will only have to add each URL once. New Adafruit boards and updates to existing boards will automatically be picked up by the Board Manager each time it is opened. The URLs point to index files that the Board Manager uses to build the list of available & installed boards.

To find the most up to date list of URLs you can add, you can visit the list of third party board URLs on the Arduino IDE wiki. We will only need to add one URL to the IDE in this example, but you can add multiple URLS by separating them with commas. Copy and paste the link below into the Additional Boards Manager URLs option in the Arduino IDE preferences.

Using with Arduino IDE

The Feather/Metro/Gemma/Trinket M0 and M4 use an ATSAMD21 or ATSAMD51 chip, and you can pretty easily get it working with the Arduino IDE. Most libraries (including the popular ones like NeoPixels and display) will work with the M0 and M4, especially devices & sensors that use I2C or SPI.

Now that you have added the appropriate URLs to the Arduino IDE preferences in the previous page, you can open the Boards Manager by navigating to the Tools->Board menu.

Once the Board Manager opens, click on the category drop down menu on the top left hand side of the window and select All. You will then be able to select and install the boards supplied by the URLs added to the preferences.

Remember you need SETUP the Arduino IDE to support our board packages - see the previous page on how to add adafruit's URL to the preferences

Install Drivers (Windows 7 & 8 Only)

Run the installer! Since we bundle the SiLabs and FTDI drivers as well, you'll need to click through the license

Select which drivers you want to install, the defaults will set you up with just about every Adafruit board!

Click Install to do the installin'

Blink

Now you can upload your first blink sketch!

Plug in the M0 or M4 board, and wait for it to be recognized by the OS (just takes a few seconds). It will create a serial/COM port, you can now select it from the drop-down, it'll even be 'indicated' as Trinket/Gemma/Metro/Feather/ItsyBitsy/Trellis!

// the setup function runs once when you press reset or power the board
void setup() {
// initialize digital pin 13 as an output.
pinMode(13, OUTPUT);
}
// the loop function runs over and over again forever
void loop() {
digitalWrite(13, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(13, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}

// the setup function runs once when you press reset or power the board
void setup() {
// initialize digital pin 13 as an output.
pinMode(13, OUTPUT);
}
// the loop function runs over and over again forever
void loop() {
digitalWrite(13, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(13, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}

And click upload! That's it, you will be able to see the LED blink rate change as you adapt the delay() calls.

If you're using Trellis M4 Express, you can go to the next page cause there's no pin 13 LED - so you won't see it blink. Still this is a good thing to test compile and upload!

If you are having issues, make sure you selected the matching Board in the menu that matches the hardware you have in your hand.

Successful Upload

If you have a successful upload, you'll get a bunch of red text that tells you that the device was found and it was programmed, verified & reset

After uploading, you may see a message saying "Disk Not EjectedProperly" about the ...BOOT drive. You can ignore that message: it's an artifact of how the bootloader and uploading work.

Compilation Issues

If you get an alert that looks like

Cannot run program "{runtime.tools.arm-none-eabi-gcc.path}\bin\arm-non-eabi-g++"

Make sure you have installed the Arduino SAMD boards package, you need both Arduino & Adafruit SAMD board packages

Manually bootloading

If you ever get in a 'weird' spot with the bootloader, or you have uploaded code that crashes and doesn't auto-reboot into the bootloader, click the RST button twice (like a double-click)to get back into the bootloader.

The red LED will pulse, so you know that its in bootloader mode.

Once it is in bootloader mode, you can select the newly created COM/Serial port and re-try uploading.

You may need to go back and reselect the 'normal' USB serial port next time you want to use the normal upload.

Ubuntu & Linux Issue Fix

Note if you're using Ubuntu 15.04 (or perhaps other more recent Linux distributions) there is an issue with the modem manager service which causes the Bluefruit LE micro to be difficult to program. If you run into errors like "device or resource busy", "bad file descriptor", or "port is busy" when attempting to program then you are hitting this issue.

Adapting Sketches to M0

The ATSAMD21 is a very nice little chip but its fairly new as Arduino-compatible cores go. Most sketches & libraries will work but here's a few things we noticed!

The below note are for all M0 boards, but not all may apply (e.g. Trinket and Gemma M0 do not have ARef so you can skip the Analog References note!)

Analog References

If you'd like to use the ARef pin for a non-3.3V analog reference, the code to use is analogReference(AR_EXTERNAL) (it's AR_EXTERNAL not EXTERNAL)

Pin Outputs & Pullups

The old-style way of turning on a pin as an input with a pullup is to use

pinMode(pin, INPUT)digitalWrite(pin, HIGH)

This is because the pullup-selection register is the same as the output-selection register.

For the M0, you can't do this anymore! Instead, use

pinMode(pin, INPUT_PULLUP)

which has the benefit of being backwards compatible with AVR.

Serial vs SerialUSB

99.9% of your existing Arduino sketches use Serial.print to debug and give output. For the Official Arduino SAMD/M0 core, this goes to the Serial5 port, which isn't exposed on the Feather. The USB port for the Official Arduino M0 core, is called SerialUSB instead.

In the Adafruit M0 Core, we fixed it so that Serial goes to USB when you use a Feather M0 so it will automatically work just fine.

However, on the off chance you are using the official Arduino SAMD core not the Adafruit version (which really, we recommend you use our version because as you can see it can vary) & you want your Serial prints and reads to use the USB port, use SerialUSB instead of Serial in your sketch

If you have existing sketches and code and you want them to work with the M0 without a huge find-replace, put

AnalogWrite / PWM on Feather/Metro M0

After looking through the SAMD21 datasheet, we've found that some of the options listed in the multiplexer table don't exist on the specific chip used in the Feather M0.

For all SAMD21 chips, there are two peripherals that can generate PWM signals: The Timer/Counter (TC) and Timer/Counter for Control Applications (TCC). Each SAMD21 has multiple copies of each, called 'instances'.

Each TC instance has one count register, one control register, and two output channels. Either channel can be enabled and disabled, and either channel can be inverted. The pins connected to a TC instance can output identical versions of the same PWM waveform, or complementary waveforms.

Each TCC instance has a single count register, but multiple compare registers and output channels. There are options for different kinds of waveform, interleaved switching, programmable dead time, and so on.

The biggest members of the SAMD21 family have five TC instances with two 'waveform output' (WO) channels, and three TCC instances with eight WO channels:

TC[0-4],WO[0-1]

TCC[0-2],WO[0-7]

And those are the ones shown in the datasheet's multiplexer tables.

The SAMD21G used in the Feather M0 only has three TC instances with two output channels, and three TCC instances with eight output channels:

TC[3-5],WO[0-1]

TCC[0-2],WO[0-7]

Tracing the signals to the pins broken out on the Feather M0, the following pins can't do PWM at all:

Analog pin A5

The following pins can be configured for PWM without any signal conflicts as long as the SPI, I2C, and UART pins keep their protocol functions:

Digital pins 5, 6, 9, 10, 11, 12, and 13

Analog pins A3 and A4

If only the SPI pins keep their protocol functions, you can also do PWM on the following pins:

TX and SDA (Digital pins 1 and 20)

analogWrite() PWM range

On AVR, if you set a pin's PWM with analogWrite(pin, 255) it will turn the pin fully HIGH. On the ARM cortex, it will set it to be 255/256 so there will be very slim but still-existing pulses-to-0V. If you need the pin to be fully on, add test code that checks if you are trying to analogWrite(pin, 255) and, instead, does a digitalWrite(pin, HIGH)

analogWrite() DAC on A0

If you are trying to use analogWrite() to control the DAC output on A0, make sure you do not have a line that sets the pin to output. Remove: pinMode(A0, OUTPUT).

Missing header files

there might be code that uses libraries that are not supported by the M0 core. For example if you have a line with

The above will also make sure that header file isn't included for other architectures

If the #include is in the arduino sketch itself, you can try just removing the line.

Bootloader Launching

For most other AVRs, clicking reset while plugged into USB will launch the bootloader manually, the bootloader will time out after a few seconds. For the M0, you'll need to double click the button. You will see a pulsing red LED to let you know you're in bootloader mode. Once in that mode, it wont time out! Click reset again if you want to go back to launching code

Aligned Memory Access

This is a little less likely to happen to you but it happened to me! If you're used to 8-bit platforms, you can do this nice thing where you can typecast variables around. e.g.

uint8_t mybuffer[4];float f = (float)mybuffer;

You can't be guaranteed that this will work on a 32-bit platform because mybuffer might not be aligned to a 2 or 4-byte boundary. The ARM Cortex-M0 can only directly access data on 16-bit boundaries (every 2 or 4 bytes). Trying to access an odd-boundary byte (on a 1 or 3 byte location) will cause a Hard Fault and stop the MCU. Thankfully, there's an easy work around ... just use memcpy!

uint8_t mybuffer[4];float f;memcpy(&f, mybuffer, 4)

Floating Point Conversion

Like the AVR Arduinos, the M0 library does not have full support for converting floating point numbers to ASCII strings. Functions like sprintf will not convert floating point. Fortunately, the standard AVR-LIBC library includes the dtostrf function which can handle the conversion for you.

Unfortunately, the M0 run-time library does not have dtostrf. You may see some references to using #include <avr/dtostrf.h> to get dtostrf in your code. And while it will compile, it does not work.

Instead, check out this thread to find a working dtostrf function you can include in your code:

Storing data in FLASH

If you're used to AVR, you've probably used PROGMEM to let the compiler know you'd like to put a variable or string in flash memory to save on RAM. On the ARM, its a little easier, simply add const before the variable name:

const char str[] = "My very long string";

That string is now in FLASH. You can manipulate the string just like RAM data, the compiler will automatically read from FLASH so you dont need special progmem-knowledgeable functions.

You can verify where data is stored by printing out the address:Serial.print("Address of str $"); Serial.println((int)&str, HEX);

If the address is $2000000 or larger, its in SRAM. If the address is between $0000 and $3FFFF Then it is in FLASH

Pretty-Printing out registers

There's a lot of registers on the SAMD21, and you often are going through ASF or another framework to get to them. So having a way to see exactly what's going on is handy. This library from drewfish will help a ton!

After restarting, check that you see the library folder with examples:

Run first example

Lets begin with the beginner project, which we can use to do basic tests. To open the ATCommand sketch, click on the File > Examples > Adafruit_BluefruitLE_nRF51 folder in the Arduino IDE and select atcommand:

This will open up a new instance of the example in the IDE, as shown below:

Don't upload the sketch yet! You will have to begin by changing the configuration.

// SHARED SPI SETTINGS
// ----------------------------------------------------------------------------------------------
// The following macros declare the pins to use for HW and SW SPI communication.
// SCK, MISO and MOSI should be connected to the HW SPI pins on the Uno when
// using HW SPI. This should be used with nRF51822 based Bluefruit LE modules
// that use SPI (Bluefruit LE SPI Friend).
// ----------------------------------------------------------------------------------------------
#define BLUEFRUIT_SPI_CS 8
#define BLUEFRUIT_SPI_IRQ 7
#define BLUEFRUIT_SPI_RST 6 // Optional but recommended, set to -1 if unused

// SHARED SPI SETTINGS
// ----------------------------------------------------------------------------------------------
// The following macros declare the pins to use for HW and SW SPI communication.
// SCK, MISO and MOSI should be connected to the HW SPI pins on the Uno when
// using HW SPI. This should be used with nRF51822 based Bluefruit LE modules
// that use SPI (Bluefruit LE SPI Friend).
// ----------------------------------------------------------------------------------------------
#define BLUEFRUIT_SPI_CS 8
#define BLUEFRUIT_SPI_IRQ 7
#define BLUEFRUIT_SPI_RST 6 // Optional but recommended, set to -1 if unused

Compilation Issues

Cannot run program "{runtime.tools.arm-none-eabi-gcc.path}\bin\arm-non-eabi-g++"

Make sure you have installed the Arduino SAMD boards package, you need both Arduino & Adafruit SAMD board packages

Manually bootloading

If you ever get in a 'weird' spot with the bootloader, or you have uploaded code that crashes and doesn't auto-reboot into the bootloader, click the RST button twice (like a double-click)to get back into the bootloader.

The red LED will pulse, so you know that its in bootloader mode.

Once it is in bootloader mode, you can select the newly created COM/Serial port and re-try uploading.

You may need to go back and reselect the 'normal' USB serial port next time you want to use the normal upload.

Run the sketch

OK check again that the correct port is selected

Then open up the Serial console. You will see the following:

This sketch starts by doing a factory reset, then querying the BLE radio for details. These details will be useful if you are debugging the radio. If you see the information as above, you're working! (Note that the dates and version numbers may vary)

AT command testing

Now you can try out some AT commands - check the rest of the learn guide for a full list. We'll just start with AT+HWGETDIETEMP which will return the approximate ambient temperature of the BLE chipset

OK now you know how to upload/test/communicate with your Feather M0 Bluefruit. Next up we have a bunch of tutorials who can follow for checking out the bluetooth le radio and apps.

For all the following examples, we share the same code between various modules so don't forget to make sure you have the RESET pin set to 4 in BluefruitConfig.h for each sketch before uploading, and that Hardware SPI mode is selected by checking for

Configuration!

Before you start uploading any of the example sketches, you'll need to CONFIGURE the Bluefruit interface - there's a lot of options so pay close attention!

Which board do you have?

There's a few products under the Bluefruit name:

If you are using the Bluefruit LE Shield then you have an SPI-connected NRF51822 module. You can use this with Atmega328 (Arduino UNO or compatible), ATmega32u4 (Arduino Leonardo, compatible) or ATSAMD21 (Arduino Zero, compatible) and possibly others. Your pinouts are Hardware SPI, CS = 8, IRQ = 7, RST = 4

Bluefruit Micro or Feather 32u4 Bluefruit

If you have a Bluefruit Micro or Feather 32u4 Bluefruit LE then you have an ATmega32u4 chip with Hardware SPI, CS = 8, IRQ = 7, RST = 4

Feather M0 Bluefruit LE

If you have a Feather M0 Bluefruit LE then you have an ATSAMD21 chip with Hardware SPI, CS = 8, IRQ = 7, RST = 4

Bluefruit LE SPI Friend

If you have a stand-alone module, you have a bit of flexibility with wiring however we strongly recommend Hardware SPI, CS = 8, IRQ = 7, RST = 4

You can use this with just about any microcontroller with 5 or 6 pins

Bluefruit LE UART Friend or Flora BLE

If you have a stand-alone UART module you have some flexibility with wiring. However we suggest hardware UART if possible. You will likely need to use the flow control CTS pin if you are not using hardware UART. There's also a MODE pin

You can use this with just about any microcontroller with at least 3 pins, but best used with a Hardware Serial/UART capable chip!

Configure the Pins Used

You'll want to check the Bluefruit Config to set up the pins you'll be using for UART or SPI

Each example sketch has a secondary tab with configuration details. You'll want to edit and save the sketch to your own documents folder once set up.

Common settings:

You can set up how much RAM to set aside for a communication buffer and whether you want to have full debug output. Debug output is 'noisy' on the serial console but is handy since you can see all communication between the micro and the BLE

Software UART

If you are using Software UART, you can set up which pins are going to be used for RX, TX, and CTS flow control. Some microcontrollers are limited on which pins can be used! Check the SoftwareSerial library documentation for more details

Mode Pin

For both hardware and software serial, you will likely want to define the MODE pin. There's a few sketches that dont use it, instead depending on commands to set/unset the mode. Its best to use the MODE pin if you have a GPIO to spare!

Refer to the table above to determine whether you have SPI or UART controlled Bluefruits!

Select the Serial Bus

Once you've configured your pin setup in the BluefruitConfig.h file, you can now check and adapt the example sketch.

The Adafruit_BluefruitLE_nRF51 library supports four different serial bus options, depending on the HW you are using: SPI both hardware and software type, and UART both hardware and software type.

UART Based Boards (Bluefruit LE UART Friend & Flora BLE)

This is for Bluefruit LE UART Friend & Flora BLE boards. You can use either software serial or hardware serial. Hardware serial is higher quality, and less risky with respect to losing data. However, you may not have hardware serial available! Software serial does work just fine with flow-control and we do have that available at the cost of a single GPIO pin.

For software serial (Arduino Uno, Adafruit Metro) you should uncomment the software serial contructor below, and make sure the other three options (hardware serial & SPI) are commented out.

ATCommand

The ATCommand example allows you to execute AT commands from your sketch, and see the results in the Serial Monitor. This can be useful for debugging, or just testing different commands out to see how they work in the real world. It's a good one to start with!

Opening the Sketch

To open the ATCommand sketch, click on the File > Examples > Adafruit_BluefruitLE_nRF51 folder in the Arduino IDE and select atcommand:

This will open up a new instance of the example in the IDE, as shown below:

Configuration

Check the Configuration! page earlier to set up the sketch for Software/Hardware UART or Software/Hardware SPI. The default is hardware SPI

If using software or hardware Serial UART:

This tutorial does not need to use the MODE pin, make sure you have the mode switch in CMD mode if you do not configure & connect a MODE pin

Don't forget to also connect the CTS pin on the Bluefruit to ground if you are not using it! (The Flora has this already done)

Running the Sketch

Once you upload the sketch to your board (via the arrow-shaped upload icon), and the upload process has finished, open up the Serial Monitor via Tools > Serial Monitor, and make sure that the baud rate in the lower right-hand corner is set to 115200:

To send an AT command to the Bluefruit LE module, enter the command in the textbox at the top of the Serial Monitor and click the Send button:

The response to the AT command will be displayed in the main part of the Serial Monitor. The response from 'ATI' is shown below:

You can do pretty much anything at this prompt, with the AT command set. Try AT+HELP to get a list of all commands, and try out ones like AT+HWGETDIETEMP (get temperature at the nRF51822 die) and AT+HWRANDOM (generate a random number)

BLEUart

The BLEUart example sketch allows you to send and receive text data between the Arduino and a connected Bluetooth Low Energy Central device on the other end (such as you mobile phone using the Adafruit Bluefruit LE Connect application for Android or iOS in UART mode).

Opening the Sketch

To open the ATCommand sketch, click on the File > Examples > Adafruit_BluefruitLE_nRF51 folder in the Arduino IDE and select bleuart_cmdmode:

This will open up a new instance of the example in the IDE, as shown below:

Configuration

Check the Configuration! page earlier to set up the sketch for Software/Hardware UART or Software/Hardware SPI. The default is hardware SPI

If using software or hardware Serial UART:

This tutorial does not need to use the MODE pin, make sure you have the mode switch in CMD mode if you do not configure & connect a MODE pin

Don't forget to also connect the CTS pin on the Bluefruit to ground if you are not using it! (The Flora has this already done)

Running the Sketch

Once you upload the sketch to your board (via the arrow-shaped upload icon), and the upload process has finished, open up the Serial Monitor via Tools > Serial Monitor, and make sure that the baud rate in the lower right-hand corner is set to 115200:

Once you see the request, use the App to connect to the Bluefruit LE module in UART mode so you get the text box on your phone

Any text that you type in the box at the top of the Serial Monitor will be sent to the connected phone, and any data sent from the phone will be displayed in the serial monitor:

You can see the incoming string here in the Adafruit Bluefruit LE Connect app below (iOS in this case):

The response text ('Why hello, Arduino!') can be seen below:

HIDKeyboard

The HIDKeyboard example shows you how you can use the built-in HID keyboard AT commands to send keyboard data to any BLE-enabled Android or iOS phone, or other device that supports BLE HID peripherals.

Opening the Sketch

To open the ATCommand sketch, click on the File > Examples > Adafruit_BluefruitLE_nRF51 folder in the Arduino IDE and select hidkeyboard:

This will open up a new instance of the example in the IDE, as shown below:

Configuration

Check the Configuration! page earlier to set up the sketch for Software/Hardware UART or Software/Hardware SPI. The default is hardware SPI

If using software or hardware Serial UART:

This tutorial does not need to use the MODE pin, make sure you have the mode switch in CMD mode!

Don't forget to also connect the CTS pin on the Bluefruit to ground if you are not using it! (The Flora has this already done)

Running the Sketch

Once you upload the sketch to your board (via the arrow-shaped upload icon), and the upload process has finished, open up the Serial Monitor via Tools > Serial Monitor, and make sure that the baud rate in the lower right-hand corner is set to 115200:

To send keyboard data, type anything into the textbox at the top of the Serial Monitor and click the Send button.

Bonding the HID Keyboard

Before you can use the HID keyboard, you will need to 'bond' it to your phone or PC. The bonding process establishes a permanent connection between the two devices, meaning that as soon as your phone or PC sees the Bluefruit LE module again it will automatically connect.

The exact procedures for bonding the keyboard will varying from one platform to another.

When you no longer need a bond, or wish to bond the Bluefruit LE module to another device, be sure to delete the bonding information on the phone or PC, otherwise you may not be able to connect on a new device!

Android

To bond the keyboard on a Bluetooth Low Energy enabled Android device, go to the Settings application and click the Bluetooth icon.

These screenshots are based on Android 5.0 running on a Nexus 7 2013. The exact appearance may vary depending on your device and OS version.

Inside the Bluetooth setting panel you should see the Bluefruit LE module advertising itself as Bluefruit Keyboard under the 'Available devices' list:

Tapping the device will start the bonding process, which should end with the Bluefruit Keyboard device being moved to a new 'Paired devices' list with 'Connected' written underneath the device name:

To delete the bonding information, click the gear icon to the right of the device name and the click the Forget button:

iOS

To bond the keyboard on an iOS device, go to the Settings application on your phone, and click the Bluetooth menu item.

The keyboard should appear under the OTHER DEVICES list:

Once the bonding process is complete the device will be moved to the MY DEVICES category, and you can start to use the Bluefruit LE module as a keyboard:

To unbond the device, click the 'info' icon and then select the Forget this Device option in the menu:

OS X

To bond the keyboard on an OS X device, go to the Bluetooth Preferences window and click the Pair button beside the Bluefruit Keyboard device generated by this example sketch:

To unbond the device once it has been paired, click the small 'x' icon beside Bluefruit Keyboard:

... and then click the Remove button when the confirmation dialogue box pops up:

Controller

The Controller sketch allows you to turn your BLE-enabled iOS or Android device in a hand-held controller or an external data source, taking advantage of the wealth of sensors on your phone or tablet.

You can take accelerometer or quaternion data from your phone, and push it out to your Arduino via BLE, or get the latest GPS co-ordinates for your device without having to purchase (or power!) any external HW.

Opening the Sketch

To open the Controller sketch, click on the File > Examples > Adafruit_BluefruitLE_nRF51 folder in the Arduino IDE and select controller:

This will open up a new instance of the example in the IDE, as shown below:

Configuration

Check the Configuration! page earlier to set up the sketch for Software/Hardware UART or Software/Hardware SPI. The default is hardware SPI

If using software or hardware Serial UART:

This tutorial will also be easier to use if you wire up the MODE pin, you can use any pin but our tutorial has pin 12 by default. You can change this to any pin. If you do not set the MODE pin then make sure you have the mode switch in CMD mode

If you are using a Flora or otherwise don't want to wire up the Mode pin, set the BLUEFRUIT_UART_MODE_PIN to -1 in the configuration tab so that the sketch will use the +++ method to switch between Command and Data mode!

Don't forget to also connect the CTS pin on the Bluefruit to ground if you are not using it! (The Flora has this already done)

Running the Sketch

Once you upload the sketch to your board (via the arrow-shaped upload icon), and the upload process has finished, open up the Serial Monitor via Tools > Serial Monitor, and make sure that the baud rate in the lower right-hand corner is set to 115200:

Using Bluefruit LE Connect in Controller Mode

Once the sketch is running you can open Adafruit's Bluefruit LE Connect application (available for Android or iOS) and use the Controller application to interact with the sketch. (If you're new to Bluefruit LE Connect, have a look at our dedicated Bluefruit LE Connect learning guide.)

On the welcome screen, select the Adafruit Bluefruit LE device from the list of BLE devices in range:

Then from the activity list select Controller:

This will bring up a list of data points you can send from your phone or tablet to your Bluefruit LE module, by enabling or disabling the appropriate sensor(s).

Streaming Sensor Data

You can take Quaternion (absolute orientation), Accelerometer, Gyroscope, Magnetometer or GPS Location data from your phone and send it directly to your Arduino from the Controller activity.

By enabling the Accelerometer field, for example, you should see accelerometer data update in the app:

The data is parsed in the example sketch and output to the Serial Monitor as follows:

You can combine the color picker and controller sample sketches to make color-configurable animations triggered by buttons in the mobile app-- very handy for wearables! Download this combined sample code (configured for Feather but easy to adapt to FLORA, BLE Micro, etc.) to get started:

// this line is particularly required for Flora, but is a good idea
// anyways for the super long lines ahead!
ble.setInterCharWriteDelay(5); // 5 ms

// this line is particularly required for Flora, but is a good idea
// anyways for the super long lines ahead!
ble.setInterCharWriteDelay(5); // 5 ms

Running the Sketch

Once you upload the sketch to your board (via the arrow-shaped upload icon), and the upload process has finished, open up the Serial Monitor via Tools > Serial Monitor, and make sure that the baud rate in the lower right-hand corner is set to 115200:

If you open up an application on your mobile device or laptop that support the standard Heart Rate Monitor Service, you should be able to see the heart rate being updated in sync with the changes seen in the Serial Monitor:

nRF Toolbox HRM Example

The image below is a screenshot from the free nRF Toolbox application from Nordic on Android (also available on iOS), showing the incoming Heart Rate Monitor data:

CoreBluetooth HRM Example

The image below is from a freely available CoreBluetooth sample application from Apple showing how to work with Bluetooth Low Energy services and characteristics:

UriBeacon

The UriBeacon example shows you how to use the built-in UriBeacon AT commands to configure the Bluefruit LE module as a UriBeacon advertiser, following Google's Physical Web UriBeacon specification.

Opening the Sketch

To open the ATCommand sketch, click on the File > Examples > Adafruit_BluefruitLE_nRF51 folder in the Arduino IDE and select uribeacon:

This will open up a new instance of the example in the IDE, as shown below. You can edit the URL that the beacon will point to, from the default http://www.adafruit.com or just upload as is to test

Configuration

Check the Configuration! page earlier to set up the sketch for Software/Hardware UART or Software/Hardware SPI. The default is hardware SPI

If using software or hardware Serial UART:

This tutorial does not need to use the MODE pin, make sure you have the mode switch in CMD mode if you do not configure & connect a MODE pin

Don't forget to also connect the CTS pin on the Bluefruit to ground if you are not using it! (The Flora has this already done)

Running the Sketch

Once you upload the sketch to your board (via the arrow-shaped upload icon), and the upload process has finished, open up the Serial Monitor via Tools > Serial Monitor, and make sure that the baud rate in the lower right-hand corner is set to 115200:

At this point you can open the Physical Web Application for Android or for iOS, and you should see a link advertising Adafruit's website:

HALP!

When using the Bluefruit Micro or a Bluefruit LE with Flora/Due/Leonardo/Micro the examples dont run?

We add a special line to setup() to make it so the Arduino will halt until it sees you've connected over the Serial console. This makes debugging great but makes it so you cannot run the program disconnected from a computer.

Solution? Once you are done debugging, remove these two lines from setup()

AT Commands

The advantage of an AT style command set is that it's easy to use in machine to machine communication, while still being somewhat user friendly for humans.

Test Command Mode '=?'

'Test' mode is used to check whether or not the specified command exists on the system or not.

Certain firmware versions or configurations may or may not include a specific command, and you can determine if the command is present by taking the command name and appending '=?' to it, as shown below

NOTE: Many commands that are means to be read will perform the same action whether they are sent to the command parser in 'execute' or 'read' mode. For example, the following commands will produce identical results:

+++

When you are in COMMAND mode, entering '+++\n' or '+++\r\n' will cause the module to switch to DATA mode, and anything typed into the console will go direct to the BLUE UART service.

To switch from DATA mode back to COMMAND mode, simply enter '+++\n' or '+++\r\n' again (be sure to include the new line character!), and a new 'OK' response will be displayed letting you know that you are back in COMMAND mode (see the two 'OK' entries in the sample code below).

Codebase Revision: 0.4.7

Parameters: None

Output: None

Note that +++ can also be used on the mobile device to send and receive AT command on iOS or Android, though this should always be used with care.

See the AT+MODESWITCHEN command to control the availability of the +++ command

# Read an integer back from position 16 in user NVM
AT+NVMREAD=16, 4, INTEGER
32768
OK

# Read an integer back from position 16 in user NVM
AT+NVMREAD=16, 4, INTEGER
32768
OK

AT+MODESWITCHEN

Enables or disables mode switches via the '+++' command on the BLE peripheral of BLE UART side of the connection.

Codebase Version: 0.7.1

Parameters:

location: This can be a string, either 'local' or 'ble' indicating which side should have the '+++' command enabled or disabled, 'local' being the Bluefruit peripheral and 'ble' being the phone or tablet.

AT+HWGETDIETEMP

Gets the temperature in degree celcius of the BLE module's die. This can be used for debug purposes (higher die temperature generally means higher current consumption), but does not corresponds to ambient temperature and can nto be used as a replacement for a normal temperature sensor.

# Set pin 14 HIGH
AT+HWGPIO=14,1
OK
# Set pin 14 LOW
AT+HWGPIO=14,0
OK
# Read the current state of pin 14
AT+HWGPIO=14
0
OK
# Try to update a pin that is not set as an output
AT+HWGPIOMODE=14,0
OK
AT+HWGPIO=14,1
ERROR

# Set pin 14 HIGH
AT+HWGPIO=14,1
OK
# Set pin 14 LOW
AT+HWGPIO=14,0
OK
# Read the current state of pin 14
AT+HWGPIO=14
0
OK
# Try to update a pin that is not set as an output
AT+HWGPIOMODE=14,0
OK
AT+HWGPIO=14,1
ERROR

AT+HWGPIOMODE

This will set the mode for the specified GPIO pin (input, output, etc.).

Codebase Revision: 0.3.0

Parameters: This command one or two values (comma-separated in the case of two parameters being used):

The pin number

The new GPIO mode, where:

0 = Input

1 = Output

2 = Input with pullup enabled

3 = Input with pulldown enabled

Output: If a single parameters is passed (the GPIO pin number) the current pin mode will be returned.

Some pins are reserved for specific functions on Bluefruit modules and can not be used as GPIO. If you try to make use of a reserved pin number an 'ERROR' response will be generated.

AT+BLEBEACON will cause the beacon data to be stored in non-volatile config memory on the Bluefruit LE module, and these values will be persisted across system resets and power cycles. To remove or clear the beacon data you need to enter the 'AT+FACTORYRESET' command in command mode.

Entering Nordic Beacon emulation using the sample code above, you can see the simulated beacon in Nordic's 'Beacon Config' tool below:

AT+BLEURIBEACON

Converts the specified URI into a UriBeacon advertising packet, and configures the module to advertise as a UriBeacon (part of Google's Physical Web project).

To view the UriBeacon URIs you can use one of the following mobile applications:

AT+EDDYSTONEURL

An optional second parameter indicates whether to continue advertising the Eddystone URL even when the peripheral is connected to a central device

Firmware 0.6.7 added an optional third parameter for the RSSI at 0 meters value. This should be measured by the end user by checking the RSSI value on the receiving device at 1m and then adding 41 to that value (to compensate for the signal strength loss over 1m), so an RSSI of -62 at 1m would mean that you should enter -21 as the RSSI at 0m. Default value is -18dBm.

Output: Firmware <= 0.6.6: none. With firmware >= 0.6.7 running this command with no parameters will return the current URL.

# Set the Eddystone URL to adafruit
AT+EDDYSTONEURL=http://www.adafruit.com
OK
# Set the Eddystone URL to adafruit and advertise it even when connected
AT+EDDYSTONEURL=http://www.adafruit.com,1
OK

# Set the Eddystone URL to adafruit
AT+EDDYSTONEURL=http://www.adafruit.com
OK
# Set the Eddystone URL to adafruit and advertise it even when connected
AT+EDDYSTONEURL=http://www.adafruit.com,1
OK

AT+EDDYSTONECONFIGEN

This command causes the Bluefruit LE module to enable the Eddystone URL config service for the specified number of seconds.

This command should be used in combination with the Physical Web application from Google, available for Android or iOS. Run this command then select the 'Edit URL' option from the app to change the destination URL over the air.

Codebase Revision: 0.6.6

Parameters: The number of seconds to advertised the config service UUID

BLE Generic

The following general purpose BLE commands are available on Bluefruit LE modules:

AT+BLEPOWERLEVEL

Gets or sets the current transmit power level for the module's radio (higher transmit power equals better range, lower transmit power equals better battery life).

Codebase Revision: 0.3.0

Parameters: The TX power level (in dBm), which can be one of the following values (from lowest to higher transmit power):

-40

-20

-16

-12

-8

-4

0

4

Output: The current transmit power level (in dBm)

The updated power level will take affect as soon as the command is entered. If the device isn't connected to another device, advertising will stop momentarily and then restart once the new power level has taken affect.

# Get the current TX power level (in dBm)
AT+BLEPOWERLEVEL
0
OK
# Set the TX power level to 4dBm (maximum value)
AT+BLEPOWERLEVEL=4
OK
# Set the TX power level to -12dBm (better battery life)
AT+BLEPOWERLEVEL=-12
OK
# Set the TX power level to an invalid value
AT+BLEPOWERLEVEL=-3
ERROR

# Get the current TX power level (in dBm)
AT+BLEPOWERLEVEL
0
OK
# Set the TX power level to 4dBm (maximum value)
AT+BLEPOWERLEVEL=4
OK
# Set the TX power level to -12dBm (better battery life)
AT+BLEPOWERLEVEL=-12
OK
# Set the TX power level to an invalid value
AT+BLEPOWERLEVEL=-3
ERROR

AT+BLEGETADDRTYPE

Gets the address type (for the 48-bit BLE device address).

Normally this will be '1' (random), which means that the module uses a 48-bit address that was randomly generated during the manufacturing process and written to the die by the manufacturer.

Random does not mean that the device address is randomly generated every time, only that a one-time random number is used.

AT+BLEGETPEERADDR

Gets the 48-bit address of the peer (central) device we are connected to.

Codebase Revision: 0.6.5

Parameters: None

Output: The 48-bit address of the connected central device in hex format. The command will return ERROR if we are not connected to a central device.

Please note that the address returned by the central device is almost always a random value that will change over time, and this value should generally not be trusted. This command is provided for certain edge cases, but is not useful in most day to day scenarios.

BLE Services

The following commands allow you to interact with various GATT services present on Bluefruit LE modules when running in Command Mode.

AT+BLEUARTTX

This command will transmit the specified text message out via the UART Service while you are running in Command Mode.

Codebase Revision: 0.3.0

Parameters: The message payload to transmit. The payload can be up to 240 characters (since AT command strings are limited to a maximum of 256 bytes total).

Output: This command will produce an ERROR message if you are not connected to a central device, or if the internal TX FIFO on the Bluefruit LE module is full.

As of firmware release 0.6.2 and higher, AT+BLEUARTTX can accept a limited set of escape code sequences:

\r = carriage return

\n = new line

\t = tab

\b = backspace

\\ = backward slash

As of firmware release 0.6.7 and higher, AT+BLEUARTTX can accept the following escape code sequence since AT+BLEUARTTX=? has a specific meaning to the AT parser:

\? = transmits a single question mark

As of firmware release 0.7.6 and higher, AT+BLEUARTTX can accept the following escape code sequence:

\+ = transmit a single '+' character without having to worry about `+++` mode switch combinations

ESCAPE SEQUENCE NOTE: If you are trying to send escape sequences in code via something like 'ble.print("...");' please note that you will need to send a double back-slash for the escape code to arrive as-intended in the AT command. For example: ble.println("AT+BLEUARTTX=Some Test\\r\\n");

# Send a string when connected to another device
AT+BLEUARTTX=THIS IS A TEST
OK
# Send a string when not connected
AT+BLEUARTTX=THIS IS A TEST
ERROR

# Send a string when connected to another device
AT+BLEUARTTX=THIS IS A TEST
OK
# Send a string when not connected
AT+BLEUARTTX=THIS IS A TEST
ERROR

TX FIFO Buffer Handling

Starting with firmware version 0.6.7, when the TX FIFO buffer is full a 200ms blocking delay will be used to see if any free space becomes available in the FIFO before returning ERROR. The exact process is detailed in the flow chart below:

Note: The TX FIFO full check will happen for each GATT transaction (of up to 20 bytes of data each), so large data transfers may have multiple 200ms wait states.

You can use the AT+BLEUARTFIFO=TX command to check the size of the TX FIFO before sending data to ensure that you have enough free space available in the buffer.

The TX FIFO has the following size, depending on the firmware version used:

Firmware <=0.6.6: 160 characters wide

Firmware >=0.6.7: 1024 characters wide

It IS possible with large data transfers that part of the payload can be transmitted, and the command can still produce an ERROR if the FIFO doesn't empty in time in the middle of the payload transfer (since data is transmitted in maximum 20 byte chunks). If you need to ensure reliable data transfer, you should always check the TX FIFO size before sending data, which you can do using the AT+BLEUARTFIFO command. If not enough space is available for the entire payload, add a SW delay until enough space is available. Any single AT+BLEUARTTX command can fit into the FIFO, but multiple large instances of this command may cause the FIFO to fill up mid transfer.

AT+BLEUARTTXF

This is a convenience function the serves the same purpose as AT+BLEUARTTX, but data is immediately sent in a single BLE packet ('F' for force packet). This command will accept a maximum of 20 characters, which is the limit of what can be send in a single packet.

Codebase Revision: 0.7.6

Parameters: See AT+BLEUARTTX

Output: See AT+BLEUARTTX

AT+BLEUARTRX

This command will dump the UART service's RX buffer to the display if any data has been received from from the UART service while running in Command Mode. The data will be removed from the buffer once it is displayed using this command.

Any characters left in the buffer when switching back to Data Mode will cause the buffered characters to be displayed as soon as the mode switch is complete (within the limits of available buffer space, which is 1024 bytes on current black 32KB SRAM devices, or 160 bytes for the blue first generation BLEFriend board based on 16KB SRAM parts).

Codebase Revision: 0.3.0

Parameters: None

Output: The RX buffer's content if any data is available, otherwise nothing.

You can also use the AT+BLEUARTFIFO=RX command to check if any incoming data is available or not.

# Command results when data is available
AT+BLEUARTRX
Sent from Android
OK
# Command results when no data is available
AT+BLEUARTRX
OK

# Command results when data is available
AT+BLEUARTRX
Sent from Android
OK
# Command results when no data is available
AT+BLEUARTRX
OK

AT+BLEUARTFIFO

This command will return the free space available in the BLE UART TX and RX FIFOs. If you are transmitting large chunks of data, you may want to check if you have enough free space in the TX FIFO before sending, keeping in mind that individual GATT packets can contain up to 20 user bytes each.

Codebase Revision: 0.6.7

Parameters: Running this command with no parameters will return two comma-separated values indicating the free space in the TX buffer, following by the RX buffer. To request a specific buffer, you can execute the command with either a "TX" or "RX" value (For example: "AT+BLEUARTFIFO=TX").

Output: The free space remaining in the TX and RX FIFO buffer if no parameter is present, otherwise the free space remaining in the specified FIFO buffer.

AT+BLEKEYBOARDEN

This command will enable GATT over HID (GoH) keyboard support, which allows you to emulate a keyboard on supported iOS and Android devices. By default HID keyboard support is disabled, so you need to set BLEKEYBOARDEN to 1 and then perform a system reset before the keyboard will be enumerated and appear in the Bluetooth preferences on your phone, where if can be bonded as a BLE keyboard.

Codebase Revision: 0.5.0

Parameters: 1 or 0 (1 = enable, 0 = disable)

Output: None

As of firmware version 0.6.6 this command is now an alias for AT+BLEHIDEN

You must perform a system reset (ATZ) before the changes take effect!

Before you can use your HID over GATT keyboard, you will need to bond your mobile device with the Bluefruit LE module in the Bluetooth preferences panel.

# Send a URI with a new line ending to execute in Chrome, etc.
AT+BLEKEYBOARD=http://www.adafruit.com\r\n
OK
# Send a single question mark (special use case, 0.6.7+)
AT+BLEKEYBOARD=\?
OK

# Send a URI with a new line ending to execute in Chrome, etc.
AT+BLEKEYBOARD=http://www.adafruit.com\r\n
OK
# Send a single question mark (special use case, 0.6.7+)
AT+BLEKEYBOARD=\?
OK

AT+BLEKEYBOARDCODE

Sends a raw hex sequence of USB HID keycodes to the BLE keyboard interface including key modifiers and up to six alpha-numeric characters.

This command accepts the following string-encoded byte array payload, matching the way HID over GATT sends keyboard data:

Byte 0: Modifier

Byte 1: Reserved (should always be 00)

Bytes 2..7: Hexadecimal value(s) corresponding to the HID keys (if no character is used you can enter '00' or leave trailing characters empty)

After a keycode sequence is sent with the AT+BLEKEYBOARDCODE command, you must send a second AT+BLEKEYBOARDCODE command with at least two 00 characters to indicate the keys were released!

Modifier Values

The modifier byte can have one or more of the following bits set:

Bit 0 (0x01): Left Control

Bit 1 (0x02): Left Shift

Bit 2 (0x04): Left Alt

Bit 3 (0x08): Left Window

Bit 4 (0x10): Right Control

Bit 5 (0x20): Right Shift

Bit 6 (0x40): Right Alt

Bit 7 (0x80): Right Window

Codebase Revision: 0.5.0

Parameters: A set of hexadecimal values separated by a hyphen ('-'). Note that these are HID scan code values, not standard ASCII values!

Output: None

HID Keyboard Codes

A list of hexademical-format HID keyboard codes can be found here (see section 7), and are listed below for convenience sake:

HID key code values don't correspond to ASCII key codes! For example, 'a' has an HID keycode value of '04', and there is no keycode for an upper case 'A' since you use the modifier to set upper case values. For details, google 'usb hid keyboard scan codes', and see the example below.

AT+BLEHIDEN

This command will enable GATT over HID (GoH) support, which allows you to emulate a keyboard, mouse or media controll on supported iOS, Android, OSX and Windows 10 devices. By default HID support is disabled, so you need to set BLEHIDEN to 1 and then perform a system reset before the HID devices will be enumerated and appear in on your central device.

Codebase Revision: 0.6.6

Parameters: 1 or 0 (1 = enable, 0 = disable)

Output: None

You normally need to 'bond' the Bluefruit LE peripheral to use the HID commands, and the exact bonding process will change from one operating system to another.

If you have previously bonded to a device and need to clear the bond, you can run the AT+FACTORYRESET command which will erase all stored bond data on the Bluefruit LE module.

AT+BLEHIDGAMEPADEN

Enables HID gamepad support in the HID service. By default the gamepad is disabled as of version 0.7.6 of the firmware since it causes problems on iOS and OS X and should only be used on Android and Windows based devices.

Codebase Revision: 0.7.6

Parameters: Whether the gamepad service should be enabled via one of the following values:

on

off

1

0

Output: If executed with no parameters, a numeric value will be returned indicating whether the battery service is enabled (1) or disabled (0).

This command requires a system reset to take effect.

AT+BLEHIDGAMEPAD

Sends a specific HID gamepad payload out over BLE

Codebase Revision: 0.7.0

Parameters: The following comma-separated parameters are available:

x: LEFT, RIGHT: If X=-1 then 'LEFT' is pressed, if X=1 then 'RIGHT' is pressed, if X=0 then neither left nor right are pressed

y: UP, DOWN: If Y=-1 then 'UP' is pressed, if Y=1 then 'DOWN' is pressed, if Y=0 then neither up nor down are pressed

buttons: 0x00-0xFF, which is a bit mask for 8 button 0-7

Output: Nothing

HID gamepad is disabled by default as of version 0.7.6, and must first be enabled via AT+BLEHIDGAMEPADEN=1 before it can be used.

Note: You need to send both 'press' and 'release' events for each button, otherwise the system will think that the button is still pressed until a release state is received.

BLE GAP

The following commands can be used to configure the GAP settings on the BLE module.

You can use these commands to modify the advertising data (for ex. the device name that appears during the advertising process), to retrieve information about the connection that has been established between two devices, or the disconnect if you no longer wish to maintain a connection.

AT+GAPCONNECTABLE

This command can be used to prevent the device from being 'connectable'.

Codebase Revision: 0.7.0

Parameters: Whether or not the device should advertise itself as connectable, using one of the following values:

yes

no

1

0

Output: The 'connectable' state of the device if no parameter is provided

AT+GAPDISCONNECT

AT+GAPDEVNAME

Gets or sets the device name, which is included in the advertising payload for the Bluefruit LE module

Codebase Revision: 0.3.0

Parameters:

None to read the current device name

The new device name if you want to change the value

Output: The device name if the command is executed in read mode

Updating the device name will persist the new value to non-volatile memory, and the updated name will be used when the device is reset. To reset the device to factory settings and clean the config data from memory run the AT+FACTORYRESET command.

AT+GAPDELBONDS

AT+GAPINTERVALS

Gets or sets the various advertising and connection intervals for the Bluefruit LE module.

Be extremely careful with this command since it can be easy to cause problems changing the intervals, and depending on the values selected some mobile devices may no longer recognize the module or refuse to connect to it.

Codebase Revision: 0.3.0

Parameters: If updating the GAP intervals, the following comma-separated values can be entered:

To save power, the Bluefruit modules automatically drop to a lower advertising rate after 'fast advertising timeout' seconds. The default value is 30 seconds ('Fast Advertising Timeout'). The low power advertising interval is hard-coded to approximately 0.6s in firmware < 0.7.0. Support to control the low power interval was added in the 0.7.0 firmware release via an optional fifth parameter.

Please note the following min and max limitations for the GAP parameters:

Absolute minimum connection interval: 10ms

Absolute maximum connection interval: 4000ms

Absolute minimum fast advertising interval: 20ms

Absolute maximum fast advertisting interval: 10240ms

Absolute minimum low power advertising interval: 20ms

Absolute maximum low power advertising interval: 10240ms

If you only wish to update one interval value, leave the other comma-separated values empty (ex. ',,110,' will only update the third value, advertising interval).

Output: If reading the current GAP interval settings, the following comma-separated information will be displayed:

Minimum connection interval (in milliseconds)

Maximum connection interval (in milliseconds)

Advertising interval (in milliseconds)

Advertising timeout (in milliseconds)

Updating the GAP intervals will persist the new values to non-volatile memory, and the updated values will be used when the device is reset. To reset the device to factory settings and clean the config data from memory run the AT+FACTORYRESET command.

# Command results when advertising data is not being sent
AT+GAPSTARTADV
OK
# Command results when we are already advertising
AT+GAPSTARTADV
ERROR
# Command results when we are connected to another device
AT+GAPSTARTADV
ERROR

# Command results when advertising data is not being sent
AT+GAPSTARTADV
OK
# Command results when we are already advertising
AT+GAPSTARTADV
ERROR
# Command results when we are connected to another device
AT+GAPSTARTADV
ERROR

AT+GAPSTOPADV

Stops advertising packets from being transmitted by the Bluefruit LE module.

AT+GAPSETADVDATA

In particular, Core Specification Supplement (CSS) v4 contains the details on common advertising data fields like 'Flags' (Part A, Section 1.3) and the various Service UUID lists (Part A, Section 1.1). A list of all possible GAP Data Types is available on the Bluetooth SIG's Generic Access Profile page.

The Advertising Data payload consists of Generic Access Profile data that is inserted into the advertising packet in the following format: [U8:LEN] [U8:Data Type Value] [n:Value]

WARNING: This command requires a degree of knowledge about the low level details of the Bluetooth 4.0 or 4.1 Core Specification, and should only be used by expert users. Misuse of this command can easily cause your device to be undetectable by central devices in radio range.

WARNING: This command will override the normal advertising payload and may prevent some services from acting as expected.

To restore the advertising data to the normal default values use the AT+FACTORYRESET command.

For example, to insert the 'Flags' Data Type (Data Type Value 0x01), and set the value to 0x06/0b00000110 (BR/EDR Not Supported and LE General Discoverable Mode) we would use the following byte array:

Including the service UUIDs is important since some mobile applications will only work with devices that advertise a specific service UUID in the advertising packet. This is true for most apps from Nordic Semiconductors, for example.

Codebase Revision: 0.3.0

Parameters: The raw byte array that should be inserted into the advertising data section of the advertising packet, being careful to stay within the space limits defined by the Bluetooth Core Specification.

# Advertise as Discoverable and BLE only with 16-bit UUIDs 0x180D and 0x180A
AT+GAPSETADVDATA=02-01-06-05-02-0d-18-0a-18
OK

# Advertise as Discoverable and BLE only with 16-bit UUIDs 0x180D and 0x180A
AT+GAPSETADVDATA=02-01-06-05-02-0d-18-0a-18
OK

The results of this command can be seen in the screenshot below, taken from a sniffer analyzing the advertising packets in Wireshark. The advertising data payload is higlighted in blue in the raw byte array at the bottom of the image, and the packet analysis is in the upper section:

BLE GATT

GATT, which standards for the Generic ATTribute Profile, governs data organization and data exchanges between connected devices. One device (the peripheral) acts as a GATT Server, which stores data in Attribute records, and the second device in the connection (the central) acts as a GATT Client, requesting data from the server whenever necessary.

The following commands can be used to create custom GATT services and characteristics on the BLEFriend, which are used to store and exchange data.

Please note that any characteristics that you define here will automatically be saved to non-volatile FLASH config memory on the device and re-initialised the next time the device starts.

You need to perform a system reset via 'ATZ' before most of the commands below will take effect!

GATT Limitations

The commands below have the following limitations due to SRAM and resource availability, which should be kept in mind when creating or working with customer GATT services and characteristics.

These values apply to firmware 0.7.0 and higher:

Maximum number of services: 10

Maximum number of characteristics: 30

Maximum buffer size for each characteristic: 32 bytes

Maximum number of CCCDs: 16

If you want to clear any previous config value, enter the 'AT+FACTORYRESET' command before working on a new peripheral configuration.

AT+GATTCLEAR

Clears any custom GATT services and characteristics that have been defined on the device.

# Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a custom service to the peripheral
AT+GATTADDSERVICE=UUID128=00-11-00-11-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
1
OK
# Add a custom characteristic to the above service (making sure that there
# is no conflict between the 16-bit UUID and bytes 3+4 of the 128-bit service UUID)
AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK

# Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a custom service to the peripheral
AT+GATTADDSERVICE=UUID128=00-11-00-11-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
1
OK
# Add a custom characteristic to the above service (making sure that there
# is no conflict between the 16-bit UUID and bytes 3+4 of the 128-bit service UUID)
AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK

AT+GATTADDCHAR

Adds a custom characteristic to the last service that was added to the peripheral (via AT+GATTADDSERVICE).

AT+GATTADDCHAR must be run AFTER AT+GATTADDSERVICE, and will add the new characteristic to the last service definition that was added.

As of version 0.6.6 of the Bluefruit LE firmware you can now use custom 128-bit UUIDs with this command. See the example at the bottom of this command description.

Codebase Revision: 0.3.0

Parameters: This command accepts a set of comma-separated key-value pairs that are used to define the characteristic properties. The following key-value pais can be used:

UUID: The 16-bit UUID to use for the characteristic (which will be insert in the 3rd and 4th bytes of the parent services 128-bit UUID). This value should be entered in hexadecimal format (ex. 'UUID=0x1234'). This value must be unique, and should not conflict with bytes 3+4 of the parent service's 128-bit UUID.

PROPERTIES: The 8-bit characteristic properties field, as defined by the Bluetooth SIG. The following values can be used:

VALUE: The initial value to assign to this characteristic (within the limits of 'MIN_LEN' and 'MAX_LEN'). Value can be an integer ("-100", "27"), a hexadecimal value ("0xABCD"), a byte array ("aa-bb-cc-dd") or a string ("GATT!").

>=0.7.0 - DATATYPE: This argument indicates the data type stored in the characteristic, and is used to help parse data properly. It can be one of the following values:

Response: The index value of the characteristic in the custom GATT characteristic lookup table. (It's important to keep track of these characteristic index values to work with the characteristic later.)

Note: Key values are not case-sensitive

Make sure that the 16-bit UUID is unique and does not conflict with bytes 3+4 of the 128-bit service UUID

# Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a custom service to the peripheral
AT+GATTADDSERVICE=UUID128=00-11-00-11-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
1
OK
# Add a custom characteristic to the above service (making sure that there
# is no conflict between the 16-bit UUID and bytes 3+4 of the 128-bit service UUID)
AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK

# Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a custom service to the peripheral
AT+GATTADDSERVICE=UUID128=00-11-00-11-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
1
OK
# Add a custom characteristic to the above service (making sure that there
# is no conflict between the 16-bit UUID and bytes 3+4 of the 128-bit service UUID)
AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK

Version 0.6.6 of the Bluefruit LE firmware added the ability to use a new 'UUID128' flag to add custom 128-bit UUIDs that aren't related to the parent service UUID (which is used when passing the 16-bit 'UUID' flag).

To specify a 128-bit UUID for your customer characteristic, enter a value resembling the following syntax:

The DESCRIPTION field is a string that contains a short text description of the characteristic. Some apps may not display this data, but it should be visible using something like the Master Control Panel application from Nordic on iOS and Android.

The first parameter is the characteristic index value, as returned from the AT+GATTADDCHAR function. This parameter is always required, and if no second parameter is entered the current value of this characteristic will be returned.

The second (optional) parameter is the new value to assign to this characteristic (within the MIN_SIZE and MAX_SIZE limits defined when creating it).

Response: If the command is used in read mode (only the characteristic index is provided as a value), the response will display the current value of the characteristics. If the command is used in write mode (two comma-separated values are provided), the characteristics will be updated to use the provided value.

History

This page tracks additions or changes to the AT command set based on the firmware version number (which you can obtain via the 'ATI' command):

Version 0.7.7

The following AT commands and features were added in the 0.7.7 release:

Added AT+BLEUARTTXF (F for force) to immediately send the specified data out in an BLE UART packet (max 20 bytes), bypassing any FIFO delays and avoiding packets potentially being transmitted in two transactions.

Adjusted BLE UART service to use min connection interval as the tx interval

Added AT+DFUIRQ to enable using the DFU Pin for IRQ purposes when there is a supported event on the nRF51822

Enabled the internal pullup resistor on the CS pin for Bluefruit SPI boards

Added AT+MODESWITCHEN to enable/disable +++ mode switching from the local (serial or SPI) or BLE UART side. By default local = enabled, ble = disabled, meaning commands can only be executed via the local interface by default.

Implemented a '\+' escape code to immediately send '+' chars without trigger the +++ delay waiting for further similar input

Added AT+BLEHIDGAMEPADEN to separately enable HID Gamepad, since iOS/OSX has a conflict with gamepad devices causing HID keyboard to not work properly.

The following bugs were fixed in release 0.7.7:

Fixed a factory reset issue when a long delay occurs in app_error_handler()

Fixed an issue where strings were being truncated at 64 chars in UART

Fixed HID keyboard support not working with iOS 9 & 10

Version 0.7.0

The following AT commands were added in the 0.7.0 release:

AT+BAUDRATEChange the HW UART baudrate

AT+UARTFLOWEnable or disable HW UART flow control

AT+BLEMIDIEN=on/off/0/1Enable/disable MIDI service, requires a reset to take affect

AT+BLEMIDITXSend a MIDI event

AT+BLEMIDIRXReceive an available MIDI event

AT+GATTCHARRAWAdded this read only command to read binary (instead of ASCII) data from a characteristic. It is non-printable but less overhead and easier for writing library in Arduino

Fixed a bug where writing from the central does not update the value on the characteristic correctly

Fixed an issue with HID examples, where when paired with Central, a disconnect then reconnect could not send HID reports anymore

Version 0.6.7

The following AT commands were added in the 0.6.7 release:

AT+BLEUARTFIFOReturns the number of free bytes available in the TX and RX FIFOs for the Bluetooth UART Service.

The following commands were changed in the 0.6.7 release:

AT+BLEUARTTXIf the TX FIFO is full, the command will wait up to 200ms to see if the FIFO size decreases before exiting and returning an ERROR response due to the FIFO being full.

AT+BLEURIBEACONThis command will go back to using the old (deprecated) UriBeacon UUID (0xFED8), and only the AT+EDDYSTONEURL command will use the newer Eddystone UUID (0xFEAA).

AT+BLEKEYBOARD and AT+BLEUARTTXThese commands now accept '\?' as an escape code since 'AT+BLEKEYBOARD=?' has another meaning for the AT parser. To send a single question mark the following command should be used: 'AT+BLEKEYBOARD=\?' or 'AT+BLEUARTTX=\?'

AT+EDDYSTONEURLThis command now accepts an optional third parameter for RSSI at 0m value (default is -18dBm). Running this command with no parameters ('AT+EDDYSTONEURL\r\n') will now return the current URL.

Key bug fixes in this release:

The FIFO handling for the Bluetooth UART Service was improved for speed and stability, and the TX and RF FIFOs were increased to 1024 bytes each.

An issue where a timer overflow was causing factory resets every 4 hours or so has been resolved.

Fixed a problem with the GATT server where 'value_len' was being incorrectly parsed for integer values in characteristics where 'max_len' >4

Version 0.6.6

The following AT commands were added in the 0.6.6 release:

AT+EDDYSTONEURLUpdate the URL for the beacon and switch to beacon mode

AT+EDDYSTONEENABLEEnable/disable beacon mode using the configured url

AT+EDDYSTONECONFIGENEnable advertising for the the Eddystone configuration service for the specified number of seconds

AT+HWMODELEDAllows the user to override the default MODE LED behaviour with one of the following options: DISABLE, MODE, HWUART, BLEUART, SPI, MANUAL

AT+BLECONTROLKEYAllows HID media control values to be sent to a bonded central device (volume, screen brightness, etc.)

AT+BLEHIDENEnables or disables BLE HID support in the Bluefruit LE firmware (mouse, keyboard and media control)

AT+BLEMOUSEMOVETo move the HID mouse

AT+BLEMOUSEBUTTONTo set the state of the HID mouse buttons

The following commands were changed in the 0.6.6 release:

AT+BLEKEYBOARDEN - Now an alias for AT+BLEHIDEN

AT+GATTADDCHAR - Added a new UUID128 field to allow custom UUIDs

Key bug fixes in this release:

Fixed issues with long beacon URLs

Fixed big endian issue in at+blebeacon for major & minor number

Known issues with this release:

Windows 10 seems to support a limited number of characteristics for the DIS service. We had to disable the Serial Number characteristic to enable HID support with windows 10.

Version 0.5.0

ATIThe SoftDevice, SoftDevice version and bootloader version were added as a new (7th) record. For Ex: "S110 7.1.0, 0.0" indicates version 7.1.0 of the S110 softdevice is used with the 0.0 bootloader (future boards will use a newer 0.1 bootloader).

Other notes concerning 0.5.0:

Starting with version 0.5.0, you can execute the AT+FACTORYRESET command at any point (and without a terminal emulator) by holding the DFU button down for 10 seconds until the blue CONNECTED LED starts flashing, then releasing it.

The results of this script can be seen below in the 'HRM' app of Nordic's nRF Toolbox application:

Please note that nRF Toolbox will only display HRM data if the value changes, so you will need to update the Heart Rate Measurement characteristic at least once after opening the HRM app and connecting to the BLEFriend

SDEP (SPI Data Transport)

In order to facilitate switching between UART and SPI based Bluefruit LE modules, the Bluefruit LE SPI Friend and Shield uses the same AT command set at the UART modules (ATI, AT+HELP, etc.).

These text-based AT commands are encoded as binary messages using a simple binary protocol we've named SDEP (Simple Data Exhange Protocol).

Most of the time, you never need to deal with SDEP directly, but we've documented the protocol here in case you need understand the Bluefruit LE SPI interface in depth!

SDEP Overview

SDEP was designed as a bus neutral protocol to handle binary commands and responses -- including error responses -- in a standard, easy to extend manner. 'Bus neutral' means that we can use SDEP regardless of the transport mechanism (USB HID, SPI, I2C, Wireless data over the air, etc.).

All SDEP messages have a four byte header, and in the case of the Bluefruit LE modules up to a 16 byte payloads. Larger messages are broken up into several 4+16 bytes message chunks which are rebuilt at either end of the transport bus. The 20 byte limit (4 byte header + 16 byte payload) was chosen to take into account the maximum packet size in Bluetooth Low Energy 4.0 (20 bytes per packet).

SPI Setup

While SDEP is bus neutral, in the case of the Bluefruit LE SPI Friend or Shield, an SPI transport is used with the following constraints and assumptions, largely to take into account the HW limitations of the nRF51822 system on chip:

SPI Hardware Requirements

The SPI clock should run <=4MHz

A 100us delay should be added between the moment that the CS line is asserted, and before any data is transmitted on the SPI bus

The CS line must remain asserted for the entire packet, rather than toggling CS every byte

The CS line can however be deasserted and then reasserted between individual SDEP packets (of up to 20 bytes each).

IRQ Pin

The IRQ line is asserted by the Bluefruit LE SPI Friend/Shield as long as an entire SDEP packet is available in the buffer on the nRF51822, at which point you should read the packet, keeping the CS line asserted for the entire transaction (as detailed above).

The IRQ line will remain asserted as long as one or more packets are available, so the line may stay high after reading a packet, meaning that more packets are still available in the FIFO on the SPI slave side.

SDEP Packet and SPI Error Identifier

Once CS has been asserted and the mandatory 100us delay has passed, a single byte should be read from the SPI bus which will indicate the type of payload available on the nRF51822 (see Message Type Indicator below for more information on SDEP message types). Keep CS asserted after this byte has been read in case you need to continue reading the rest of the frame.

If a standard SDEP message type indicator (0x10, 0x20, 0x40 or 0x80) is encountered, keep reading as normal. There are two other indicators that should be taken into account, though, which indicate a problem on the nRF51822 SPI slave side:

This means there are six possible response bytes reading the message type indicator (the first byte read after an SDEP command is sent): 0x10, 0x20, 0x40, 0x80, which indicate a valid message type, or 0xFE, 0xFF which indicate an error condition.

Sample Transaction

The following image shows a sample SDEP response that is spread over two packets (since the response is > 20 bytes in size). Notice that the IRQ line stays asserted between the packets since more than one packet was available in the FIFO on the Bluefruit LE SPI side:

SDEP (Simple Data Exchange Protocol)

The Simple Data Exchange Protocol (SDEP) can be used to send and receive binary messages between two connected devices using any binary serial bus (USB HID, USB Bulk, SPI, I2C, Wireless, etc.), exchanging data using one of four distinct message types (Command, Response, Alert and Error messages).

The protocol is designed to be flexible and extensible, with the only requirement being that individual messages are 20 bytes or smaller, and that the first byte of every message is a one byte (U8) identifier that indicates the message type, which defines the format for the remainder of the payload.

Endianness

All values larger than 8-bits are encoded in little endian format. Any deviation from this rule should be clearly documented.

Message Type Indicator

The first byte of every message is an 8-bit identifier called the Message Type Indicator. This value indicates the type of message being sent, and allows us to determine the format for the remainder of the message.

Message Type

Command

Response

Alert

Error

ID (U8)

0x10

0x20

0x40

0x80

SDEP Data Transactions

Either connected device can initiate SDEP transactions, though certain transport protocols imposes restrictions on who can initiate a transfer. The master device, for example, always initiates transactions with Bluetooth Low Energy or USB, meaning that slave devices can only reply to incoming commands.

Every device that receives a Command Message must reply with a Response Message, Error Message or Alert message.

Message Types

Command Messages

Command messages (Message Type = 0x10) have the following structure:

Name

Message Type

Command ID

Payload Length

Payload

Type

U8

U16

U8

...

Meaning

Always '0x10'

Unique Command Identifier

[7] More data [6-5] Reserved [4-0] Payload length (0..16)

Optional command payload (parameters, etc.)

Command ID (bytes 1-2) and Payload Length (byte 3) are mandatory in any command message. The message payload is optional, and will be ignored if Payload Length is set to 0 bytes. When a message payload is present, it’s length can be anywhere from 1..16 bytes, to stay within the 20-byte maximum message length.

A long command (>16 bytes payload) must be divided into multiple packets. To facilitate this, the More data field (bit 7 of byte 3) is used to indicate whether additional packets are available for the same command. The SDEP receiver must continue to reads packets until it finds a packet with More data == 0, then assemble all sub-packets into one command if necessary.

The contents of the payload are user defined, and can change from one command to another.

The first byte is the Message Type (0x10), which identifies this as a command message.

The second and third bytes are 0x1234 (34 12 in little-endian notation), which is the unique command ID. This value will be compared against the command lookup table and redirected to an appropriate command handler function if a matching entry was found.

The fourth byte indicates that we have a message payload of 1 byte

The fifth byte is the 1 byte payload: 0xFF

Response Messages

Response messages (Message Type = 0x20) are generated in response to an incoming command, and have the following structure:

Name

Message Type

Command ID

Payload Length

Payload

Type

U8

U16

U8

Meaning

Always '0x20'

Command ID this message is a response to

[7] More data [6-5] Reserved [4-0] Payload length (0..16)

Optional response payload (parameters, etc.)

By including the Command ID that this response message is related to, the recipient can more easily correlate responses and commands. This is useful in situations where multiple commands are sent, and some commands may take a longer period of time to execute than subsequent commands with a different command ID.

Response messages can only be generate in response to a command message, so the Command ID field should always be present.

A long response (>16 bytes payload) must be divided into multiple packets. Similar to long commands, the More data field (bit 7 of byte 3) is used to indicate whether additional packets are available for the same response. On responses that span more than one packet, the More data bit on the final packet will be set to 0 to indicate that this is the last packet in the sequence. The SDEP receiver must re-assemble all sub-packets in into one payload when necessary.

If more precise command/response correlation is required a custom protocol should be developed, where a unique message identifier is included in the payload of each command/response, but this is beyond the scope of this high-level protocol definition.

The first byte is the Message Type (0x40), which identifies this as an alert message.

The second and third bytes are 0xABCD, which is the unique alert ID.

The fourth byte indicates that we have a message payload of 4 bytes.

The last four bytes are the actual payload: 0x10000742 in this case, assuming we were transmitting a 32-bit value in little-endian format.

Standard Alert IDs

Alert IDs in the range of 0x0000 to 0x00FF are reserved for standard SDEP alerts, and may not be used by custom alerts.

The following alerts have been defined as a standard part of the protocol:

ID

0x0000

0x0001

0x0002

0x0003

Alert

Reserved

System Reset

Battery Low

Battery Critical

Description

Reserved for future use

The system is about to reset

The battery level is low

The battery level is critically low

Error Messages

Error messages (Message Type = 0x80) are returned whenever an error condition is present on the system, and have the following structure:

Name

Message Type

Error ID

Reserved

Type

U8

U16

U8

Meaning

Always '0x80'

Unique ID for the error condition

Reserved for future use

Whenever an error condition is present and the system needs to be alerted (such as a failed request, an attempt to access a non-existing resource, etc.) the system can return a specific error message with an appropriate Error ID.

Standard Error IDs

Error IDs in the range of 0x0000 to 0x00FF are reserved for standard SDEP errors, and may not be used by custom errors.

The following errors have been defined as a standard part of the protocol:

ID

0x0000

0x0001

0x0003

Error

Reserved

Invalid CMD ID

Invalid Payload

Description

Reserved for future use

CMD ID wasn't found in the lookup table

The message payload was invalid

Existing Commands

At present, there are only four SDEP commands implemented in the Bluefruit SPIFRIEND32 firmware:

SDEP_CMDTYPE_INITIALIZE = 0xBEEF

SDEP_CMDTYPE_AT_WRAPPER = 0x0A00

SDEP_CMDTYPE_BLE_UARTTX = 0x0A01

SDEP_CMDTYPE_BLE_UARTRX = 0x0A02

SDEP_CMDTYPE_INITIALIZE can be used to reset the SDEP system when a HW RST line isn't available.

The two SDEP_CMDTYPE_UART* commands send data over the BLE UART service.

SDEP_CMDTYPE_AT_WRAPPER is the command you will use most of the time, which is a wrapper that sends AT commands over the binary SDEP transport. This isn't terribly efficient, and a binary mechanism would have taken less bytes per command, but it allows the reuse of all of the earlier AT parser commands without having to implement one wrapper for every command which would significantly increase the overall code size.

SDEP AT Wrapper Usage

To use the SDEP AT Wrapp you simply send the correct header, along with the AT command you which to send to the parser. For example:

UART Service

This service simulates a basic UART connection over two lines, TXD and RXD.

It is based on a proprietary UART service specification by Nordic Semiconductors. Data sent to and from this service can be viewed using the nRFUART apps from Nordic Semiconductors for Android and iOS.

This service is available on every Bluefruit LE module and is automatically started during the power-up sequence.

Characteristics

Nordic’s UART Service includes the following characteristics:

NameTXRX

MandatoryYesYes

UUID0x00020x0003

TypeU8[20]U8[20]

R

X

WX

N

X

I

R = Read; W = Write; N = Notify; I = Indicate

Characteristic names are assigned from the point of view of the Central device

TX (0x0002)

This characteristic is used to send data back to the sensor node, and can be written to by the connected Central device (the mobile phone, tablet, etc.).

RX (0x0003)

This characteristic is used to send data out to the connected Central device. Notify can be enabled by the connected device so that an alert is raised every time the TX channel is updated.

Software Resources

To help you get your Bluefruit LE module talking to other Central devices, we've put together a number of open source tools for most of the major platforms supporting Bluetooth Low Energy.

Bluefruit LE Client Apps and Libraries

Adafruit has put together the following mobile or desktop apps and libraries to make it as easy as possible to get your Bluefruit LE module talking to your mobile device or laptop, with full source available where possible:

Bluetooth Low Energy support was added to Android starting with Android 4.3 (though it was only really stable starting with 4.4), and we've already released Bluefruit LE Connect to the Play Store.

The full source code for Bluefruit LE Connect for Android is also available on Github to help you get started with your own Android apps. You'll need a recent version of Android Studio to use this project.

This OS X desktop application is based on the same V2.x codebase as the iOS app, and gives you access to BLE UART, basic Pin I/O and OTA DFU firmware updates from the convenience of your laptop or mac.

This is a great choice for logging sensor data locally and exporting it as a CSV, JSON or XML file for parsing in another application, and uses the native hardware on your computer so no BLE dongle is required on any recent mac.

This experimental command line tool is unsupported and provided purely as a proof of concept, but can be used to allow firmware updates for Bluefruit devices from the command line.

This utility performs automatic firmware updates similar to the way that the GUI application does, by checking the firmware version on your Bluefruit device (via the Device Information Service), and comparing this against the firmware versions available online, downloading files in the background if appropriate.

Simply install the pre-compiled tool via the DMG file and place it somewhere in the system path, or run the file locally via './bluefruit' to see the help menu:

This native OS X application is a basic proof of concept app that allows you to connect to your Bluefruit LE module using most recent macbooks or iMacs. You can get basic information about the modules and use the UART service to send and receive data.

ABLE (Adafruit Bluefruit LE Desktop) is a cross-platform desktop application based on Sandeep Misty's noble library and the Electron project from Github (used by Atom).

It runs on OS X, Windows 7+ and select flavours of Linux (Ubuntu tested locally). Windows 7 support is particularly interesting since Windows 7 has no native support for Bluetooth Low Energy but the noble library talks directly to supported Bluetooth 4.0 USB dongles to emulate BLE on the system (though at this stage it's still in early BETA and drops the connection and takes more care to work with).

This app allows you to collect sensor data or perform many of the same functionality offered by the mobile Bluefruit LE Connect apps, but on the desktop.

As a proof of concept, we've played around a bit with getting Python working with the native Bluetooth APIs on OS X and the latest version of Bluez on certain Linux targets.

There are currently example sketches showing how to retreive BLE UART data as well as some basic details from the Device Information Service (DIS).

This isn't an actively support project and was more of an experiment, but if you have a recent Macbook or a Raspberry Pi and know Python, you might want to look at Adafruit_Python_BluefruitLE in our github account.

Debug Tools

If your sense of adventure gets the better of you, and your Bluefruit LE module goes off into the weeds, the following tools might be useful to get it back from unknown lands.

These debug tools are provided purely as a convenience for advanced users for device recovery purposes, and are not recommended unless you're OK with potentially bricking your board. Use them at your own risk.

Adafruit's nRF51822 Flasher is an internal Python tool we use in production to flash boards as they go through the test procedures and off the assembly line, or just testing against different firmware releases when debugging.

It relies on AdaLink or OpenOCD beneath the surface (see above), but you can use this command line tool to flash your nRF51822 with a specific SoftDevice, Bootloader and Bluefruit firmware combination.

It currently supports using either a Segger J-Link or STLink/V2 via AdaLink, or GPIO on a Raspberry Pi if you don't have access to a traditional ARM SWD debugger. (A pre-built version of OpenOCD for the RPi is included in the repo since building it from scratch takes a long time on the original RPi.)

We don't provide active support for this tool since it's purely an internal project, but made it public just in case it might help an adventurous customer debrick a board on their own.

BLE FAQ

Can I talk to Classic Bluetooth devices with a Bluefruit LE modules?

No. Bluetooth Low Energy and 'Classic' Bluetooth are both part of the same Bluetooth Core Specification -- defined and maintained by the Bluetooth SIG -- but they are completely different protocols operating with different physical constraints and requirements. The two protocols can't talk to each other directly.

Can my Bluefruit LE module connect to other Bluefruit LE peripherals

No, the Bluefruit LE firmware from Adafruit is currently peripheral only, and doesn't run in Central mode, which would cause the module to behave similar to your mobile phone or BLE enabled laptop.

If you required Central support, you should look at the newer nRF52832 based products like the Adafruit Feather nRF52 Bluefruit LE, which contains a SoftDevice which is capable of running in either Central or Peripheral mode. The nRF518322 based products (such as the one used in this learning guide) are not capable of running in Central mode because it isn't supported by the SoftDevice they use, and it isn't possible to update the SoftDevice safely without special hardware.

I just got my Bluefruit board and when I run a sketch it hangs forever on the 'Connecting...' stage!

There are several possible explanations here, but the first thing to try is to:

Disconnect and close the Bluefruit LE Connect app if it's open

Disable BLE on your mobile device

Restart your Bluefruit sketch and HW

Turn BLE back on again (on the mobile device)

Open the Bluefruit LE Connect mobile app again and try to connect again

If problems persist, try performing a Factory Reset of your device (see the appropriate learning guide for details on how to do this since it varies from one board to another).

Why are none of my changes persisting when I reset with the sample sketches?

In order to ensure that the Bluefruit LE modules are in a known state for the Adafruit demo sketches, most of them perform a factory reset at the start of the sketch.

This is useful to ensure that the sketch functions properly, but has the side effect of erasing any custom user data in NVM and setting everything back to factory defaults every time your board comes out of reset and the sketch runs.

To disable factory reset, open the demo sketch and find the FACTORYRESET_ENABLE flag and set this to '0', which will prevent the factory reset from happening at startup.

If you don't see the 'FACTORYRESET_ENABLE' flag in your .ino sketch file, you probably have an older version of the sketches and may need to update to the latest version via the Arduino library manager.

Do I need CTS and RTS on my UART based Bluefruit LE Module?

Using CTS and RTS isn't strictly necessary when using HW serial, but they should both be used with SW serial, or any time that a lot of data is being transmitted.

The reason behind the need for CTS and RTS is that the UART block on the nRF51822 isn't very robust, and early versions of the chip had an extremely small FIFO meaning that the UART peripheral was quickly overwhelmed.

Using CTS and RTS significantly improves the reliability of the UART connection since these two pins tell the device on the other end when they need to wait while the existing buffered data is processed.

To enable CTS and RTS support, go into the BluefruitConfig.h file in your sketch folder and simply assign an appropriate pin to the macros dedicated to those functions (they may be set to -1 if they aren't currently being used).

Enabling both of these pins should solve any data reliability issues you are having with large commands, or when transmitting a number of commands in a row.

How can I update to the latest Bluefruit LE Firmware?

The easiest way to keep your Bluefruit LE modules up to date is with our Bluefruit LE Connect app for Android or Bluefruit LE Connect for iOS. Both of these apps include a firmware update feature that allows you to automatically download the latest firmware and flash your Bluefruit LE device in as safe and painless a manner as possible. You can also roll back to older versions of the Bluefruit LE firmware using these apps if you need to do some testing on a previous version.

Which firmware version supports 'xxx'?

We regularly release Bluefruit LE firmware images with bug fixes and new features. Each AT command in this learning guide lists the minimum firmware version required to use that command, but for a higher level overview of the changes from one firmware version to the next, consult the firmware history page.

Does my Bluefruit LE device support ANCS?

ANCS is on the roadmap for us (most likely in the 0.7.x release family), but we don't currently support it since there are some unusual edge cases when implementing it as a service.

My Bluefruit LE device is stuck in DFU mode ... what can I do?

If your device is stuck in DFU mode for some reason and the firmware was corrupted, you have several options.

First, try a factory reset by holding down the DFU button for about 10 seconds until the CONN LED starts flashing, then release the DFU button to perform a factory reset.

If this doesn't work, you may need to reflash your firmware starting from DFU mode, which can be done in one of the following ways:

Bluefruit LE Connect (Android)

Place the module in DFU mode (constant LED blinky)

Open Bluefruit LE Connect

Connect to the 'DfuTarg' device

Once connected, you will see a screen with some basic device information. Click the '...' in the top-right corner and select Firmware Updates

Click the Use Custom Firmware button

Select the appropriate .hex and .init files (copied from the Bluefruit LE Firmware repo) ... for the BLEFRIEND32 firmware version 0.6.7, this would be:

Hex File: blefriend32_s110_xxac_0_6_7_150917_blefriend32.hex

Init File: blefriend32_s110_xxac_0_6_7_150917_blefriend32_init.dat

Click Start Update

Unfortunately, the iOS app doesn't yet support custom firmware updates from DFU mode yet, but we will get this into the next release.

Nordic nRF Toolbox

You can also use Nordic's nRF Toolbox application to update the firmware using the OTA bootloader.

Upload the .zip file containing the application.hex and application.dat files to your iPhone using uTunes, as described here

Open the nRF Toolbox app (using the latest version)

Click the DFU icon

Click the Select File text label

Switch to User Files to see the .zip file you uploaded above

Select the .zip file (ex. blefriend32_065.zip)

On the main screen select Select File Type

Select application

On the main screen select SELECT DEVICE

Select DfuTarg

Click the Upload button which should now be enabled

This will begin the DFU process and your Bluefruit LE module will reset when the update is complete

If you get the normal 2 or 3 pulse blinky pattern, the update worked!

Adafruit_nRF51822_Flasher

As a last resort, if you have access to a Raspberry Pi, a Segger J-Link or a STLink/V2, you can also try manually reflashing the entire device, as described in the FAQ above, with further details on the Software Resources page.

How do I reflash my Bluefruit LE module over SWD?

Reflashing Bluefruit LE modules over SWD (ex. switching to the sniffer firmware and back) is at your own risk and can lead to a bricked device, and we can't offer any support for this operation! You're on your own here, and there are unfortunately 1,000,000 things that can go wrong, which is why we offer two separate Bluefruit LE Friend boards -- the sniffer and the normal Bluefruit LE Friend board with the non-sniffer firmware, which provides a bootloader with fail safe features that prevents you from ever bricking boards via OTA updates.

AdaLink (SWD/JTAG Debugger Wrapper)

Transitioning between the two board types (sniffer and Bluefruit LE module) is unfortunately not a risk-free operation, and requires external hardware, software and know-how to get right, which is why it isn't covered by our support team.

That said ... if you're determined to go down that lonely road, and you have a Segger J-Link (which is what we use internally for production and development), or have already erased your Bluefruit LE device, you should have a look at AdaLink, which is the tool we use internally to flash the four files required to restore a Bluefruit LE module. (Note: recent version of AdaLink also support the cheaper STLink/V2, though the J-Link is generally more robust if you are going to purchase a debugger for long term use.)

If you are trying to flash the sniffer firmware (at your own risk!), you only need to flash a single .hex file, which you can find here. The sniffer doesn't require a SoftDevice image, and doesn't use the fail-safe bootloader -- which is why changing is a one way and risky operation if you don't have a supported SWD debugger.

Adafruit_nF51822_Flasher

We also have an internal python tool available that sits one level higher than AdaLink (referenced above), and makes it easier to flash specific versions of the official firmware to a Bluefruit LE module. For details, see the Adafruit_nRF51822_Flasher repo.

Can I access BETA firmware releases?

The latest versions of the Bluefruit LE Connect applications for iOS and Android allow you to optionally update your Bluefruit LE modules with pre-release or BETA firmware.

This functionality is primarilly provided as a debug and testing mechanism for support issues in the forum, and should only be used when trying to identify and resolve specific issues with your modules!

Enabling BETA Releases on iOS

Make sure you have at least version 1.7.1 of Bluefruit LE Connect

Go to the Settings page

Scroll to the bottom of the Settings page until you find Bluefruit LE

Click on the Bluefruit LE icon and enable the Show beta releases switch

You should be able to see any BETA releases available in the firmware repo now when you use Bluefruit LE Connect

Enabling BETA Releases on Android

Make sure you have the latest version of Bluefruit LE Connect

Open the Bluefruit LE Connect application

Click the "..." icon in the top-right corner of the app's home screen

Select Settings

Scroll down to the Software Updates section and enable Show beta releases

You should be able to see any BETA releases available in the firmware repo now when you use Bluefruit LE Connect

Why can't I see my Bluefruit LE device after upgrading to Android 6.0?

In Android 6.0 there were some important security changes that affect Bluetooth Low Energy devices. If location services are unavailable (meaning the GPS is turned off) you won't be able to see Bluetooth Low Energy devices advertising either. See this issue for details.

What is the theoretical speed limit for BLE?

This depends on a variety of factors, and is determined by the capabilities of the central device (the mobile phone, etc.) as much as the peripheral.

Taking the HW limits on the nR51822 into account (max 6 packets per connection interval, and a minimum connection interval of 7.5ms) you end up with the following theoretical limits on various mobile operating systems:

There are also some limits imposed by the Bluefruit LE firmware, but we are actively working to significantly improve the throughput in the upcoming 0.7.0 release, which will be available Q2 2016. The above figures are useful as a theoretical maximum to decide if BLE is appropriate for you project or not.

No. All of our Bluefruit LE modules currently operate in peripheral mode, which means they can only advertise their own existence via the advertising payload. The central device (usually your phone or laptop) is responsible for listening for these advertising packets, starting the connection process, and inititating any transactions between the devices. There is no way for a Bluefruit module to detect other Bluefruit modules or central devices in range, they can only send their own advertising data out and wait for a connection request to come in.

How can I determine the distance between my Bluefruit module and my phone in m/ft?

The short answer is: you can't.

RF devices normally measure signal strength using RSSI, which stands for Received Signal Strength Indicator, which is measured in dBm. The closer the devices are the strong the RSSI value generally is (-90dBm is much weaker than -60dBm, for example), but there is no reliable relationship between RSSI values in dBm and distance in the real world. If there is a wall between devices, RSSI will fall. If there is a lot of interference on the same 2.4GHz band, RSSI will fall. Depending on the device, if you simply change the antenna orientation, RSSI will fall. You can read the RSSI value between two connected devices with the AT+BLEGETRSSI command, but there are no meaningful and repeatable conclusions that can be drawn from this value about distance other than perhaps 'farther' or 'closer' in a very loose sense of the terms.

How far away from my phone can I have my Bluefruit LE module?

This depends on a number of factors beyond the module itself such as antenna orientation, the antenna design on the phone, transmit power on the sending node, competing traffic in the same 2.4GHz bandwidth, obstacles between end points, etc.

It could be as low as a couple meters up to about 10 meters line of sight, but generally Bluetooth Low Energy is designed for very short range and will work best in the 5-6 meter or less range for reliable communication, assuming normal Bluefruit firmware settings.

How many GATT services and characteristics can I create?

For firmware 0.7.0 and higher, the following limitations are present:

Maximum number of services: 10

Maximum number of characteristics: 30

Maximum buffer size for each characteristic: 32 bytes

Maximum number of CCCDs: 16

Is it possible to modify or disable the built in GATT services and characteristics (DIS, DFU, etc.)?

No, unfortunately you can't. We rely on the Device Information Service (DIS) contents to know which firmware and bootloader version you are running, and wouldn't be able to provide firmware updates without being able to trust this information, which i why it's both mandatory and read only.

Similarly, the DFU service is mandatory to maintain over the air updates and disabling it would create more problems that it's presence would cause.

How can I use BlueZ and gatttool with Bluefruit modules?

BlueZ has a bit of a learning curve associated with it, but you can find some notes below on one option to send and receive data using the BLE UART Service built into all of our Bluefruit LE modules and boards.

These commands may change with different versions of BlueZ. Version 5.21 was used below.

Can I use the IRQ pin to wake my MCU up from sleep when BLE UART data is available?

No, on SPI-based boards the IRQ pin is used to indicate that an SDEP response is available to an SDEP command. For example, when you sent the `AT+BLEUARTRX` command as an SDEP message, the Bluefruit firmware running on the nRF51822 will parse the message, prepare an SDEP response, and trigger the IRQ pin to tell the MCU that the response is ready. This is completely independant from the BLE UART service, which doesn't have interrupt capability at present.

Can I also update the sketch running on the device using Bluefruit LE Connect?

No, only the core firmware can be updated over the air. Sketches need to be loaded using the Arduino IDE and serial bootloader.

The video below is out of date and applies to early versions of the board before the Bluefruit LE Connect apps were available for iOS, Android and OS X in the respective app stores. To keep your device up to date, simply install and open the Bluefruit LE Connect app and connect to your Bluefruit device. If a firmware update is available, it will be automatically proposed, and the entire update process will be handled transparently for you.

You can reprogram the Bluefruit LE module itself over-the-air using an Android or iOS phone/tablet. This doesn't reprogram the ATmega32u4 in the Bluefruit Micro, only the BLE module itself. Since its not a common thing to do, its a little challenging to do.

You will need to disconnect/unpower the Bluefruit Micro, connect a wire temporarily between the DFU pin and GND and then power up the board via USB or battery.

Datasheets

Schematic

Fab Print

Device Recovery

Sometimes, bad things unfortunately happen. Thankfully, 99% of the time it's purely a SW issue and the Bluefruit devices have a robust bootloader with some fail safes that can almost always recover your device.

How to Recover a Bluefruit Board

1. Force DFU Mode at Startup

The first step is to force your board into a special bootloader mode, which will prevent any faulty user sketches or corrupted config data from causing problems.

Connect the DFU pin to GND with a jumper cable, or if your board has a DFU button hold the button down when adding power to your board (connecting the USB cable, etc.)

Once the device is powered, you should see a faster DFU MODE blinky pattern that lets you know you are in bootloader mode.

Now remove the jumper cable between DFU and GND (to prevent going into DFU mode when you reset)

Remove the jumper cable between DFU and GND once you are in DFU mode so that you exit it during the next reset!

2. Update the Bluefruit Firmware

Next, update your device to the latest Bluefruit firmware using the Bluefruit LE Connect app. We regularly fix bugs, and it's always a good idea to be on the latest release.

You can perform a firmware update in DFU mode, although the Bluefruit board may appear as DfuTarg in the Bluefruit LE Connect app, and you will will need to select the right firmware 'family' for you board.

Because bootloader mode is a fail safe mode and has a small subset of Bluefruit's features, we can't tell the Bluefruit LE Connect app very many details about our HW. As such, you will need to indicate which firmware type to flash ... specifically, whether to flash the UART of SPI based firmware. Be sure to select the right one, based on your product and the table below:

3. Flash a Test Sketch

// the setup function runs once when you press reset or power the board
void setup() {
// initialize digital pin LED_BUILTIN as an output.
pinMode(LED_BUILTIN, OUTPUT);
}
// the loop function runs over and over again forever
void loop() {
digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}

// the setup function runs once when you press reset or power the board
void setup() {
// initialize digital pin LED_BUILTIN as an output.
pinMode(LED_BUILTIN, OUTPUT);
}
// the loop function runs over and over again forever
void loop() {
digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}

4. Perform a Factory Reset

Once the core Bluefruit firmware has been updated, the final step is to perform a factory reset.

With the board still powered up, connect the DFU pin to GND

Leave the pin set to GND (or hold the DFU button down) for >5 seconds until the BLUE status LED starts to blink

Remove the DFU jumper cable or release the DFU button

This will cause a factory reset which will wipe all config data, and should restore your board, getting you back to a normal state in most situations!

Still Having Problems?

Hop on over to our support forums clearly explaining your problem along with the following information, and, we'll be happy to help:

You product name and ideally the product ID

The Bluefruit firmware version you are using (available at the top of the Serial Monitor output on most example sketches)

The Operating System your are using

The Arduino IDE version you are using

Providing the above information in your first post will skip a round of two of back and forth and you'll get an answer from us quicker, saving everyone time and effort!

Be sure to see the FAQ section of this learning guide as well, which has answer to many common problems!

Feather HELP!

Even though this FAQ is labeled for Feather, the questions apply to ItsyBitsy's as well!

My ItsyBitsy/Feather stopped working when I unplugged the USB!

A lot of our example sketches have a

while (!Serial);

line in setup(), to keep the board waiting until the USB is opened. This makes it a lot easier to debug a program because you get to see all the USB data output. If you want to run your Feather without USB connectivity, delete or comment out that line

My Feather never shows up as a COM or Serial port in the Arduino IDE

Avast number of Itsy/Feather 'failures' are due to charge-only USB cables

We get upwards of 5 complaints a day that turn out to be due to charge-only cables!

Use only a cable that you know is for data syncing

If you have any charge-only cables, cut them in half throw them out. We are serious! They tend to be low quality in general, and will only confuse you and others later, just get a good data+charge USB cable

Ack! I "did something" and now when I plug in the Itsy/Feather, it doesn't show up as a device anymore so I cant upload to it or fix it...

No problem! You can 'repair' a bad code upload easily. Note that this can happen if you set a watchdog timer or sleep mode that stops USB, or any sketch that 'crashes' your board

Turn on verbose upload in the Arduino IDE preferences

Plug in Itsy or Feather 32u4/M0, it won't show up as a COM/serial port that's ok

Open up the Blink example (Examples->Basics->Blink)

Select the correct board in the Tools menu, e.g. Feather 32u4, Feather M0, Itsy 32u4 or M0 (physically check your board to make sure you have the right one selected!)

Compile it (make sure that works)

Click Upload to attempt to upload the code

The IDE will print out a bunch of COM Ports as it tries to upload. During this time, double-click the reset button, you'll see the red pulsing LED that tells you its now in bootloading mode

The board will show up as the Bootloader COM/Serial port

The IDE should see the bootloader COM/Serial port and upload properly

I can't get the Itsy/Feather USB device to show up - I get "USB Device Malfunctioning" errors!

This seems to happen when people select the wrong board from the Arduino Boards menu.

If you have a Feather 32u4 (look on the board to read what it is you have) Make sure you select Feather 32u4 for ATMega32u4 based boards! Do not use anything else, do not use the 32u4 breakout board line.

If you have a Feather M0 (look on the board to read what it is you have) Make sure you select Feather M0 - do not use 32u4 or Arduino Zero

If you have a ItsyBitsy M0 (look on the board to read what it is you have) Make sure you select ItsyBitsy M0 - do not use 32u4 or Arduino Zero

I'm having problems with COM ports and my Itsy/Feather 32u4/M0

Theres two COM ports you can have with the 32u4/M0, one is the user port and one is the bootloader port. They are not the same COM port number!

When you upload a new user program it will come up with a user com port, particularly if you use Serial in your user program.

If you crash your user program, or have a program that halts or otherwise fails, the user COM port can disappear.

When the user COM port disappears, Arduino will not be able to automatically start the bootloader and upload new software.

So you will need to help it by performing the click-during upload procedure to re-start the bootloader, and upload something that is known working like "Blink"

I don't understand why the COM port disappears, this does not happen on my Arduino UNO!

UNO-type Arduinos have a seperate serial port chip (aka "FTDI chip" or "Prolific PL2303" etc etc) which handles all serial port capability seperately than the main chip. This way if the main chip fails, you can always use the COM port.

M0 and 32u4-based Arduinos do not have a seperate chip, instead the main processor performs this task for you. It allows for a lower cost, higher power setup...but requires a little more effort since you will need to 'kick' into the bootloader manually once in a while

OUT OF STOCK NOTIFICATION

YOUR NAME

YOUR EMAIL

You have been successfully subscribed to the Notification List for this product and will therefore receive an e-mail from us when it is back in stock!

For security reasons, an e-mail has been sent to you acknowledging your subscription. Please remember that this subscription will not result in you receiving any e-mail from us about anything other than the restocking of this item.

If, for any reason, you would like to unsubscribe from the Notification List for this product you will find details of how to do so in the e-mail that has just been sent to you!