s

Genuino101 CurieBle CallbackLED


2 introduce

With this tutorial use the Genuino101's onboard Bluetooth Low Energy capabilities
to turn on and of the LED connected to Pin 13 from a smartphone. You create a
LED service that polls the central and creates BLE events that are maaged with
callbacks. The values are sent using nRF Master Control Panel app, available for
Android and iOS.

3 test

3.1 on the smartphone

To drive the onboard LED of genuino101, you need the nF Master Control Panel
for Android. Launch it and do a SCAN. You should find the LEDCB tab with
a connect button.

Tap on connect, and you find the description of our BLE service offered by the
101 board. The unknown service has a UUID 19B10000-E8F2-537E-4F6C-D104768A1214
and it is set by the

BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214");

statement at the beginning of the sketch.

Tap the Unknown Service to open up its characteristic. It includes properties
that can be written with a Write Request. you also find two icons on the right
of the Unknow Characteristic. The arrow pointing down means read, the other
means write.

Tap the arrow pointing up to open the Write value popup, then set the data
type to UINT 8 and tap on the line to write your chosen value(either "0" or "1").
As soon as you tap on send the value is sent to 101 board and the LED instantly
changes accordingly.

4 code analysis

#include <CurieBLE.h>

CurieBLE.h is the library that gives access to all the parameters, features and
functions of the BLE module of the 101 board.

BLEPeripheral blePeripheral;

The BLE peripheral device is typically the board you are programming. Peripheral
connects to the central to expose its characteristics.

BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214");

The BLE service allows you to create the service you want to show through your
BLE device.

BLECharCharacteristic switchChar("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);
  • UUID
  • properties: what remote clients will be able to get notifications if this
    characteristic changes. It can assume the following value:
    • BLERead
    • BLEWrite
    • BLENotify
blePeripheral.setLocalName("LEDCB");

sets the local name of your BLE peripheral.

blePeripheral.addAttribute(ledService);
blePeripheral.addAttribute(switchChar);

adds an attribute to the peripheral.

blePeripheral.setEventHandler(BLEConnected, blePeripheralConnectHandler);
blePeripheral.setEventHandler(BLEDisconnected, blePeripheralDisconnectHandler);
switchChar.setEventHandler(BLEWritten, switchCharacteristicWritten);

sets the callback function to be called in case of match with the chosen event.

The following functions are callbacks driven by the BLE events.
blePeripheralConnectHandler() - called when BLE central connects to the 101
board.

blePeripheralDisconnectHandler() - called when BLE central disconnects from
the 101 board.

switchCharacteristicWritten() - called when BLE central writes the switch
characteristic. It switches LED on or off depending on the value written to
that characteristic by the user on the nRF Master Control Panel.

blePeripheral.begin();

begin advertising BLE service.

blePeripheral.poll();

Poll the radio for events.

6 BLE knowledge

Bluetooth 4.0 includes both traditional Bluetooth, now labeled "Bluetooth Classic",
and the new Bluetooth Low Energy(Bluetooth LE, or BLE). BLE is optimized for low
power use at low data rates, and was designed to operate from simple lithium coin
cell batteries.

Unlike standard bluetooth communication basically based on an asynchronous serial
connection (UART) a Bluetooth LE radio acts like a community bulletin board. The
computers that connect to it are like community members that read the bulletin
board. Each radio acts as either the bulletin board or the reader. If your radio
is a bulletin board (called a peripheral device in Bluetooth LE parlance) it
posts data for all radios in the community to read. If your radio is a reader
(called a central device in Bluetooth LE terms) it reads from any of the bulletin
boards (peripheral devices) that have information about which it cares. You can
also think of peripheral devices as the servers in a client-server transaction,
because they contain the information that reader radios ask for. Similarly,
central devices are the clients of the Bluetooth LE world because they read
information available from the peripherals.

Think of a Bluetooth LE peripheral device as a bulletin board and central devices
as viewers of the board. Central devices view the services, get the data, then
move on. Each transaction is quick(a few milliseconds), so multiple central
devices can get data from one peripheral. (Note that: if the peripheral has been
connected by one central, other central devices will not see it.)

The information presented by a peripheral is structured as services, each of
which is subdivided into characteristics. You can think of services as the
notices on a bulletin board, and characteristics as the individual paragraphs
of those notices. If you're a peripheral device, you just update each service
characteristic when it needs updating and don't worry about whether the central
devices read them or not. If you're a central device, you connect to the
peripheral then read the boxes you want. If a given characteristic is readable
and writable, then the peripheral and central can both change it.

6.1 notify

The Bluetooth LE specification includes a mechanism known as notify that lets
you know when data's changed. When notify on a characteristic is enabled and the
sender writes to it, the new value is automatically sent to the receiver, without
the receiver explicitly issuing a read command. This is commonly used for streaming
data such as accelerometer or other sensor readings. There's a variation on this
specification called indicate which works similarly, but in the indicate spe-
cification, the reader sends an acknowledgement of the pushed data.

The client-server structure of Bluetooth LE, combined with the notify characteristic,
is generally called a publish-and-subscribe-model.

6.2 update a characteristic

Your peripheral should update characteristics when there's a significant change
to them. For example, when a switch changes from off to on, update its characteristic.
When an analog sensor changes by a significant amount, update its characteristic.
Just as with writing to a characteristic, you could update your characteristics
on a regular interval, but this wastes processing power and energy if the
characteristic has not changed.

6.3 central and peripheral devices

Central devices are clients. They read and write data from peripheral devices.
Peripheral devices are servers. They provide data from sensors as readable
characteristics, and provide read/writable characteristics to control actuators
like motors, lights, and so forth.

6.4 services, characteristics, and UUIDs

A BLE peripheral will provide services, which in turn provide characteristics.
You can define your own services, or use standard services.
https://www.bluetooth.com/specifications/gatt/services

Services are identified by unique numbers known as UUIDs. You know about UUIDs
from other contexts. Standard services have a 16-bit UUID and custom services
have a 128-bit. The ability to define services and characteristics depends on
the radio you're using and its firmware.

6.5 service design patterns

A characteristic value can be up to 20 bytes long. This is a key constraint in
designing services. Given this limit, you should consider how best to store
data about your sensors and actuators most effectively for your application.
The simplest design pattern is to store one sensor or actuator value per
characteristic, in ASCII encoded values.

Characteristc value
Accelerometer X 200
Accelerometer Y 134

This is also the most expensive in memory terms, and would take the longest to
read. But it's the simplest for development and debugging.
You could also combine readings into a single characteristic, when a given sensor
or actuator has associated with it.

Characteristic value
Motor Speed, Direction 150,1
Accelerometer X, Y 200,134

This is more efficient, but you need to be careful not to exceed the 20-byte
limit.

6.6 read/write/notify/indicate

There are 4 things a central device can do with a characteristic:

  • Read: ask the peripheral to send back the current value of the characteristic.
    Often used for characteristics that don't change very often, for example
    characteristics used for configuration, version numbers, etc.
  • Write: modify the value of the characteristic. Often used for things that are
    like commands, for example telling the peripheral to turn a motor on or off.
  • Indicate and Notify: ask the peripheral to continuously send updated values
    of the characteristic, without the central having to constantly ask for it.

6.7 adverting and GAP

BLE devices let other devices know that they exist by advertising using the
General Access Profile (GAP). Adverting packets can contain a device name,
some other information, and also a list of the services it provides.

Advertising packets have a limited size. You will only be able to fit a single
128-bit service UUID in the packet. Make sure the device name is not too long,
or you won't even be able to fit that.

You can provide additional services that are not advertised. Central devices
will learn about these through the connection/bonding process. Non-advertised
services cannot be used to discover devices, though. Sometimes this is not an
issue. For example, you may have a custom peripheral device with a custom
service, but in your central device app you may know that it also provides the
Battery Service and other services.

6.8 GATT

The Bluetooth LE protocol operates on multiple layers. General Attribute Profile (GATT)
is the layer that defines services and characteristics and enables read/write/
notify/indicate operations on them. When reading more about GATT, you may encounter
GATT concepts of a "server" and "client". These don't always correspond to central
and peripherals. In most cases, though, the peripheral is the GATT server (since
it provides the services and characteristics), while the central is the GATT client.