iOS Integration with BLE Enabled LED Device

How to Project IOS Integration with BLE Enabled LED Device.?

In this project, you will learn how to reverse engineer a smart LED bulb that uses Bluetooth Low Energy (BLE) to change its color. As the LED bulb uses Bluetooth Low Energy (a subset of Bluetooth 4.0) it means any iOS device can theoretically control the BLE enabled LED bulb. But to control the bulb the protocol for communicating with it must be understood.

You need to familiarize yourself with SN dashboard and Bluetooth Low Energy by first reading this introductory guide. This will help you understand terminology like GATT, service, and characteristic. Continue to learn iOS Integration with BLE Enabled LED Device.

Smart Nightlight (SN) Dashboard

It allows iOS users quickly and easily set up operating mode of their device to monitor and configure the Smart Nightlight (SN) from a dedicated iOS App. User is enabled to quickly update the schedule for SN short term day or permanent week, update the SN firmware, update the SN system clock, set child button operation mode and monitor battery condition.

Overall, this software is needed to be visually appealing, lean, intuitive and helpful as a fully functional parameters configuration tool.

Scope

The scope of this project will mainly be within the realm of the SN API that we will be using (which uses BLE software stack APIs). The inputs for the application will originate from both the user and the SN. Outputs will include the application interface as it displays the information to the user and data uploads generated by the user to the SN database.

To use the SN Dashboard, a Bluetooth Smart (4.0 or newer) or BLE device is required and the API of the device must support the BLE API. Currently the following iOS devices are supported:

• iPhone 4S and newer

• iPad (3) and newer

• iPad mini

• iPod Touch (5 gen)

Functional Description and Model

The following description with illustration describes the major functions that make up the SN Dashboard application, including interface and user interaction :

Description

Here you will learn various functions within the application. The details described in a simple diagram of SN capabilities:

• Child Button

• LEDs control (color / Intensisy)

• Bluetooth Wireless Interface

• Database

 

Following priorities (handled by the SN itself) helps to configure LEDs :

• Mobile application LED Proof CTRL (test mode to validate led color

& intensity)

• When activated, the child button operation has main priority.

• Then, when active, a temporary day schedule has second priority

• Lastly, the permanent week schedule is used to configure the LEDs

behavior.

Behavioral Description and Model

Here, a description of the behavior of the software is presented.

Events

A listing of events (control, items) that will cause behavioral change within the system is presented as follows:

Open App for Pairing

The application must be paired with at least a SN. New user pair at least a SN to use the application.

SN configuration

All SN are provided with factory initial identical configuration (default factory settings). Once paired a SN must be configured with at least a child name identifier if the application detects the factory value for this specific field. In the SN configuration section, users can program, save or use an existing saved week permanent schedule to/from the SN. As an important characteristic, this configuration must be easily visualized. The user must program the fixed light activation periods of the SN’s LEDs for each days of the week. A same day configuration can be done for group of days.Until the complete week is settled, the user can add any group of days . By default the SN is provided with 2 groups of days (working days and weekend).

The LEDs fixed light activation periods includes:

• LEDs intensity and color

• LEDs ON or OFF time markers (transitions)

• When enabled (end-periods time-out)

Dashboard

It acts as a heart of the application, the goal of the dashboard is to allow the user to select a specific SN to be displayed on the dashboard (user can switch between multiple SN, one at a specific time) and rapidly visualize the current day schedule of a specific SN.

The Dashboard is always opened first to the Dashboard section, when a configured SN is paired with the application. The dashboard simply displays the most useful SN information:

1 Paired SN devices Available

2 User’s active SN on the dashboard

• Current or Today’s schedule of the SN

• The temporary day schedule (if active) remaining days

• The permanent week schedule name

• Child Nightlight CTRL Operation Mode

• Battery Level

• Charging mode

• SN clock (read, set, force update)

A lean visual representation of the SN Today’s schedule must be representing to the user. Functional example below (the example below isn’t a requirement and is only provided as a reference for the better understanding only):

 By swiping start/end time markers or time period, the user can either create/modify a temporary day schedule or directly change the permanent week schedule programmed to this specific SN. For a specific SN the user can also rapidly select another Week Schedule stored in the application memory and configure the selected SN with this new permanent week schedule.

Application settings

Light color & intensity selection

A tool must be designed for a common light color & intensity selection to seamlessly configure both the fixed light activation periods within schedules as well as configure the light activation of the child button operating mode. Primarily for every light color and intensity selection, the SN receives a 24 bit information value which specifies both the color & intensity using the RGB standard: 8-bit R, 8-bit G, 8-bit B.

The ease the visualization for the user, using a peripheral RGB wheel could be a good option for the color selection:

Note: The user can select the center of the wheel, which is white color.

And below, a dimmer will be used to increase or decrease the light intensity. Basically, intensity of the light is accomplish by increasing/decreasing the R, G and B component with the same proportion, until value reach 0 (min) or 255 (max).

States

Auto update system clocks and calendar

Upon each connection to a SN on the pairing process or when selected on the Dashboard, the application compares the SN clock & calendar information with the user’s iOS/Android information. When, different, the application may updates the SN system clock & calendar information.

The below action must be validated:

1. If difference with mobile below 5 minutes : auto-update

2. If difference with mobile greater than 30 min: pop notification to user, the user need to accept auto-update or cancel.

Battery level & charging mode

When active on the dashboard, the application refreshes the SN battery level and charging mode information.

Basics of BLE-GATT

 

Bluetooth Low Energy, or Bluetooth Smart, is a part of the Bluetooth v4.0 specification aimed at providing a fast and low-power method of communicating with wireless sensors and peripherals.

There are four primary roles that a device can fulfill in the Bluetooth LE paradigm:

• Broadcaster

• Observer

• Central

• Peripheral

BLE is primarily built around the ‘Generic Attribute profile’, or GATT. This profile defines a structured approach to how peripherals expose data to other devices. Peripheral information is organized as a collection of Services that describe logical functions of the device. A specific sensor or feature would have its own service. Each Service includes a collection of Characteristics to transfer discrete data values between devices. A Characteristic can represent service data or configuration data.

Exploring GATT to Integrate BLE Device 

The first step to figuring out how the LED works is to investigate the GATT services exposed by the LED. GATT, or generic attribute profile, is a protocol to integrate with a BLE device. Device exposes a list of services, and each service exposes a list of characteristics which can be read and/or written by a BLE application.

You can see master control panel lists all of the BLE devices that are advertising themselves. The most important thing to note here is the address of the device, e.g 5C:31:3E:F2:16:13. The address is a unique ID that will be different for every device.

Next, Touch the connect button to connect and discover the GATT services exposed by the BLE device:

You can see the BLE device exposes a handful of services. Notice each service has a UUID (universal unique ID) and some of the services have been recognized by master control panel as ‘general services’ defined by the BLE specifications. Short 4 hex character (16 bit) UUIDs identify these common services, like 0x180A, 0x1803, etc.

When a service is clicked on it drills down into the characteristics exposed by the service. Here, the device information service and characteristics can be seen :

Service: Generic Access

UUID: 1800

The generic_access service contains generic information about the device. All available Characteristics are read only.

Characteristic: Device Name

UUID: 2A00

The value of this characteristic is a UTF-8 string representing the name of the device.

Characteristic: Appearance

UUID: 2A01

The external appearance of this device. The values are composed of a category (10-bits) and sub-categories (6-bits).

Service: Device Information

UUID: 180A

This service exposes manufacturer information about a device. The Device Information Service is instantiated as a Primary Service. Only one instance of the Device Information Service is exposed on a device.

Characteristic: Model Number String

UUID: 2A24

The value of this characteristic is a UTF-8 string representing the model number assigned by the device vendor.

Characteristic: System ID

UUID: 2A23

The SYSTEM ID characteristic consists of a structure with two fields. The first field are the LSOs and the second field contains the MSOs. This is a 64-bit structure which consists of a 40-bit manufacturer-defined identifier concatenated with a 24 bit unique Organizationally Unique Identifier (OUI).

Characteristic: Serial Number String

UUID: 2A25

The value of this characteristic is a variable-length UTF-8 string representing the serial number for a

particular instance of the device.

Characteristic: Hardware Revision String

UUID: 2A27

The value of this characteristic is a UTF-8 string representing the hardware revision for the hardware

within the device.

Characteristic: Firmware Revision String

UUID: 2A26

The value of this characteristic is a UTF-8 string representing the firmware revision for the firmware within the device.

Characteristic: Software Revision String

UUID: 2A28

The value of this characteristic is a UTF-8 string representing the software revision for the software within the device.

Service: LED Service

UUID: 7A5A0000-D04B-48EB-B3FA-32EB4F0FFAC4

The LED Service is used to manually control the state of the four RGB LEDs.

Characteristic: LED Power Enable

UUID: 7A5A0001-D04B-48EB-B3FA-32EB4F0FFAC4

Globally enable or disable the LEDs supply.

Characteristic: LED Link

UUID: 7A5A0002-D04B-48EB-B3FA-32EB4F0FFAC4

When activated, it links the color and intensity of LED #2, #3 and #4 to the color and intensity of LED #1.

Characteristic: LED #1 Color

UUID: 7A5A0011-D04B-48EB-B3FA-32EB4F0FFAC4

LED #1 color and intensity in RGB format.

Name Blue Format unsigned 8-bit integer Access read, write Value 0 – 255

Characteristic: LED #2 Color

UUID: 7A5A0012-D04B-48EB-B3FA-32EB4F0FFAC4

LED #2 color and intensity in RGB format.

Characteristic: LED #3 Color

UUID: 7A5A0013-D04B-48EB-B3FA-32EB4F0FFAC4

LED #3 color and intensity in RGB format.

Characteristic: LED #4 Color

UUID: 7A5A0014-D04B-48EB-B3FA-32EB4F0FFAC4

LED #4 color and intensity in RGB format.

Characteristic: ON Time

UUID: 3CF04BD7-6812-4934-A000-DA99E0E27494

Set for how long the LEDs should stay ON when the user press the button.

Characteristic: Daily Usage

UUID: 5405D754-7055-4B8C-8153-05D87A3F8C26

Specify how many time per day the LEDs can be activated using the child button.

Characteristic: Deactivation Time

UUID: 683ED29F-AAB0-473F-A944-C22444B3ADDE

Specify a daily period of time where the child button function is deactivated.

Characteristic: Shake Mode Control

UUID: CA22EE9A-90C3-4631-8761-947DF10F72D0

When enabled, the child can shake its SN to slowly alter the colors of the LEDs.

Control With BLE Adapter

Now, control the LED bulb using a BLE adapter on a computer, for e.g. Raspberry Pi, Bluetooth 4.0 USB adapter. Unfortunately, no cross-platform Bluetooth stack or API is available that works across Windows, Mac, Linux, etc. So you’ll need to look at that platform’s Bluetooth Low Energy stack and API, if you want to use a different platform.

To setup the Bluetooth dongle and bluez, follow the steps in the setting up section of the Pi Beacon guide here.

• Confirm you can access gatttool by running ‘gatttool –help‘ (without quotes) to see the usage information of the tool.

• Brought up the Bluetooth USB adapter on the Pi by running the command hciconfig to find the name of the adapter (it should be hci0 assuming it’s the only Bluetooth adapter connected to the Pi).

• Then run ‘sudo hciconfig hci0 up‘ (without quotes) to turn on the adapter. Finally run hciconfig again should showthe adapter is in the UP RUNNING state.

• Now that the adapter is up, scan for BLE devices by running the command: sudo hcitool lescan

• Information about nearby BLE devices will be displayed. Press Ctrl-C to stop the scanning process. Notice ‘my LED bulb address’ and name are visible during the scan.

Note:

If you don’t see your LED bulb in the scan then make sure it is turned on and that no devices are connected to the bulb. Remember BLE only allows one device to be connected at a time so if you left the bulb’s control application or a BLE GATT app running then it might still be connected to the bulb and preventing you from finding the bulb. Close out of all apps using the LED bulb and try running the scan again until you see the LED bulb being advertised.

• Run the bluez GATT tool to interact with the bulb. Run command to start GATT tool’s command shell: sudo gatttool -I

• When a command prompt will be shown, type help and press enter to see a list of commands.

• Now connect to the LED bulb by issuing a connect command: connect
• Enter the address of the bulb that was found with the previous scan command. After a moment a ‘Connection successful’ message should be displayed.

• Once connected to the bulb some commands can be run to examine the bulb in more detail. In particular the primary command will list services exposed by the bulb.

• The output of the primary command is a raw list of the characteristic handles and service UUIDs implemented by the LED bulb, same as earlier information when exploring the GATT, but with a bit lower level of detail.

• You can see the characteristic handle 0x0028 falls within the range of the 0x1802 service UUID (for UUIDS that have the form 0000xxxx-0000-1000-8000-00805f9b34fb they are officially recognized UUIDs and are abbreviated with the shorter 16-bit UUID).
• Looking at the ‘Bluetooth services list’ the 0x1802 service is the ‘Immediate Alert service’, which is typically used for proximity sensors and similar devices. LED bulb may appears to be using this service to control its color.
• Run the char-desc command to get details on a particular characteristic.
• Run this command to query the 0x0028 characteristic: char-desc 0x0028 0x0028

(both 0x0028 values are necessary as the command takes a range of beginning and ending handles)

• Now you can change the color of the bulb by writing to characteristic based on what was seen from sniffing the protocol?

e.g. Execute following commands to write new values to the 0x0028 alert level characteristic:

	char-write-cmd 0x0028 58010301ff00ff0000
	char-write-cmd 0x0028 58010301ff0000ff00
	char-write-cmd 0x0028 58010301ff000000ff
	char-write-cmd 0x0028 58010301ff00000000
char-write-cmd 0x0028 58010301ff00ffffff

Here it is! You can see the LED bulb changes its colors after each command was run!

In above writing 58010301ff00ff0000 made the bulb turn red,

58010301ff0000ff00 turned the bulb green, and

58010301ff000000ff turned the bulb blue.

Sending RGB colors of 000000 and ffffff turned the bulb off and on at full bright white respectively too.

This confirms from the protocol reverse engineering, the last 3 bytes of the message represent the red, green, and blue color of the bulb.

By learning above protocols, it would be a real fun for you by controlling the light from code.  If you are a more experienced BLE user you might realize that GATT tool can be controlled from the command line directly.  If you’d like to try yourself you can grab the script from this repository and install its dependencies by executing these commands on the Pi: