Overview

BLE (Bluetooth Low Energy, low-energy Bluetooth — the version of Bluetooth technology designed for power saving: low power, fast connection, small data only) is the most common short-range wireless communication used by IoT devices. The Ai-WB2 module has a built-in BLE 4.2 Bluetooth protocol stack that works alongside Wi-Fi: Wi-Fi handles high-volume networking, BLE handles lightweight connections. This page is the concept chapter of the BLE series — first clarifying the "roles" and "rules" of the BLE world to lay the groundwork for the hands-on tutorials; this series has 5 pages total, starting from this page: iBeacon Advertising → BLE Master → BLE Slave → blufi Provisioning.

In plain words: BLE is like a small, power-saving "messenger". Regular Bluetooth is like a high-power broadcasting station — power-hungry, able to send large files; BLE is like a whisper-quiet messenger — power-saving, small data only. Communication is like "making friends": one side first advertises (like shouting through a loudspeaker: "I'm here!"), the other side scans (hears it) and comes over to connect; once connected, the two sides exchange notes according to the agreed rules (GATT). Your wristband, earphones and remote control all use this flow.

This tutorial is based on the official Ai-Thinker SDK (Ai-Thinker-Open/Ai-Thinker-WB2, version release_bl_iot_sdk_1.6.40); all examples in this series come from the official applications/bluetooth/ directory, and the code can be found directly in the local SDK.

🎯Page GoalBuild the BLE concept framework: role division, advertising and scanning, GATT services and characteristics, UUID and MAC address — laying the groundwork for the hands-on tutorials that follow.

🧰Prerequisites① Ai-WB2 development board (used by the hands-on pages that follow) ② Development environment set up per [SDK Installation](../../sdk/sdk_intro).

🔗RelatedHands-on pages in this series: [iBeacon Advertising](./ibeacon), [BLE Master](./ble_master), [BLE Slave](./ble_slave), [blufi Provisioning](./blufi).

---

①

Meet BLE: Low-Energy Bluetooth

1. BLE (Bluetooth Low Energy) is the version of Bluetooth technology designed for power saving: fast connection, low power, small data only. Your phone, wristband and earphones use it.
2. Compared with regular “classic Bluetooth” (audio/file transfer, power-hungry), BLE is like a “whisper-quiet messenger”: fewer errands, less power — perfect for battery-powered devices like sensors and remote controls.

💡 The Ai-WB2’s Wi-Fi and BLE can work simultaneously without interfering with each other: Wi-Fi handles high-volume networking, BLE handles lightweight connections (like the provisioning below).

②

Meet the Roles: Master and Slave

There are two roles in the BLE world; a device can only take one of them:

• Master: the proactive side, responsible for scanning (looking for) others and initiating connections — like you holding a phone “looking for friends”.
• Slave: the passive side, advertising constantly and waiting for others to connect — like a shop assistant standing at the roadside holding a “Welcome” sign.

Role	In plain words	Who plays it
Master	The “phone” that actively scans and connects	Phones, computers
Slave	The “wristband” that passively waits for connections	Wristbands, sensors, Ai-WB2

💡 The same Ai-WB2 board can play different roles by flashing different firmware: the BLE Master tutorial makes it the master, the BLE Slave tutorial makes it the slave.

③

Advertising and Scanning

1. Advertising: the slave periodically sends a small packet of data (device name, MAC address, custom content) — like shouting through a loudspeaker: “I’m here, I’m XX!”. Advertising doesn’t establish a connection; anyone can hear it.
2. Scanning: the master opens its “ears” to listen for who’s shouting, and decides whether to come over and connect based on the advertised content.

💡 iBeacon (Apple’s Bluetooth beacon solution) only advertises and never connects — like a roadside billboard: passers-by can see the content without shaking hands with it. This series’ iBeacon tutorial will implement it by hand.

④

Meet GATT: Services and Characteristics

1. GATT (Generic Attribute Profile) is the “rules” of communication between Bluetooth devices: it defines how data is organized and read/written. Once BLE devices connect, they exchange data by these rules.
2. GATT data is organized hierarchically, like “app → button” on your phone:
   • Service: a functional module (e.g. “heart rate service”, “battery service”) — like an app on your phone.
   • Characteristic: a specific switch or piece of data within a service (e.g. “heart rate value”, “battery percentage”) — like a button or text field inside an app.
3. The steps to communicate with a device: find its services → find the characteristics in the services → read/write the characteristics. Like opening an app first, then tapping the buttons inside.

💡 The BLE Slave tutorial in this series registers a custom service and reads/writes its characteristics with a phone app, so you experience this set of “rules”.

⑤

UUID and MAC Address

1. UUID (Universally Unique Identifier): the “ID card number” of the Bluetooth world — 16 bytes, written like B9407F30-F5F8-466E-AFF9-25556B57FE6D, uniquely identifying a service or characteristic.
2. MAC address: the “house number” of every Bluetooth device (6 bytes, e.g. 88:88:88:88:88:88); the master uses it to find and connect to a specific device.

Term	In plain words	What it’s for
UUID	ID card number	Identifies services/characteristics — tells others “what this data is”
MAC address	House number	Identifies devices — tells others “which device I am”

⑥

Hands-On Roadmap of This Series

Concepts in place — the next 4 pages are all hands-on (in sidebar order):

• iBeacon Advertising: turn the board into a “roadside billboard” — advertise only, never connect
• BLE Master: the board plays the “phone” — actively scans, connects to a slave and transparently transfers data both ways
• BLE Slave: the board plays the “wristband” — provides a transparent transfer service, waiting for a phone/master to connect
• blufi Provisioning: use a phone app to “enter” the Wi-Fi account/password into the board over Bluetooth (provisioning — sending the Wi-Fi credentials to a device, like enrolling a fingerprint on a door lock)

📜 Want to see “what a BLE program looks like”? The Full Code at the end previews the entry code of the official iBeacon example; line-by-line explanation is in the iBeacon tutorial.

---

API Summary for This Tutorial

This page is a concept chapter — no code was run; below is a preview of the core BLE APIs the hands-on pages in this series will use (signatures match the official SDK headers; detailed explanations are in each page):

bl_sys_init

Initializes basic resources such as the system clock and peripherals; must be called before using BLE (the first thing the official example main() does).

Return: 0 on success; negative error code on failure

ble_controller_init(task_priority)

Initializes the BLE protocol stack (the "brain" of Bluetooth communication) — the first step of BLE code.

Parameters:

• task_priority: protocol stack task priority (uint8_t); the official example passes configMAX_PRIORITIES - 1 (highest priority)

Return: none

bt_enable(cb)

Turns on the Bluetooth protocol stack — like turning on the "Bluetooth switch" on a phone.

Parameters:

• cb: stack-ready callback (bt_ready_cb_t), shaped void cb(int err); pass NULL if not needed

Return: 0 on success; negative error code on failure

bt_set_name(name)

Sets the Bluetooth device name — this is what appears in the phone's scan list.

Parameters:

• name: the device name string, required (e.g. "MY_IBEACON")

Return: 0 on success; negative error code on failure

bt_le_adv_start(param, ad, ad_len, sd, sd_len)

Starts BLE advertising (the "loudspeaker shout"); the advertised data is specified by the ad array.

Parameters:

• param: advertising parameter structure pointer (bt_le_adv_param_t), including the advertising interval, connectable options, etc.
• ad: advertising data array (bt_data_t), required
• ad_len: number of advertising data entries
• sd: scan response data array; pass NULL if not needed
• sd_len: number of scan response entries; pass 0

Return: 0 on success; negative error code on failure

---

Full Code

This page is a concept page without an example project of its own; here we preview the main.c entry code of the official iBeacon example project, identical to the official example (applications/bluetooth/ble_ibeacon/ble_ibeacon/main.c), to give you a visual impression of "what a BLE program looks like" — line-by-line explanation is in the iBeacon tutorial:

📜 Click to expand the iBeacon example main.c full code (preview)

/*
 * Copyright (c) 2020 Bouffalolab.
 *
 * This file is part of
 *     *** Bouffalolab Software Dev Kit ***
 *      (see www.bouffalolab.com).
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *   1. Redistributions of source code must retain the above copyright notice,
 *      this list of conditions and the following disclaimer.
 *   2. Redistributions in binary form must reproduce the above copyright notice,
 *      this list of conditions and the following disclaimer in the documentation
 *      and/or other materials provided with the distribution.
 *   3. Neither the name of Bouffalo Lab nor the names of its contributors
 *      may be used to endorse or promote products derived from this software
 *      without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
#include <stdio.h>
#include <string.h>
#include <FreeRTOS.h>
#include <task.h>
#include <blog.h>
#include <stdio.h>
#include <cli.h>
#include <blog.h>
#include <bl_uart.h>
#include <bl_sys.h>
#include "hci_driver.h"
#include "ble_lib_api.h"
#include "bluetooth.h"
#include "gatt.h"
#include "uuid.h"
#include <hosal_uart.h>
#define PRIORITIE_OFFSET    4
/*set ibeacon name*/
#define IBEACON_NAME "MY_IBEACON"

/*ibeacon data*/
char my_ibeacon[]=
{
    0x4C, 0x00, //公司的标志 (0x004C == Apple)
	0x02, 0x15, //iBeacon advertisement indicator
	0xB9, 0x40, 0x7F, 0x30, 0xF5, 0xF8, 0x46, 0x6E, 0xAF, 0xF9, 0x25, 0x55, 0x6B, 0x57, 0xFE, 0x6D, // iBeacon proximity uuid
	0x00, 0x01, // major 
	0x00, 0x01, // minor 
	0xc5 //power
};

static struct bt_data ibeacon_data[2] = 
{
	BT_DATA_BYTES(BT_DATA_FLAGS, (BT_LE_AD_GENERAL | BT_LE_AD_NO_BREDR)),
    BT_DATA(BT_DATA_MANUFACTURER_DATA, my_ibeacon, sizeof(my_ibeacon)),//
};

/*start ble advertise*/
void ble_start_advertise(void)
{
    struct bt_le_adv_param param;
    param.id = BT_ID_DEFAULT;
    param.interval_min = BT_GAP_ADV_FAST_INT_MIN_2;
    param.interval_max = BT_GAP_ADV_FAST_INT_MAX_2;
    //param.options =  BT_LE_ADV_OPT_USE_NAME | BT_LE_ADV_OPT_ONE_TIME;
    param.options = BT_LE_ADV_OPT_CONNECTABLE | BT_LE_ADV_OPT_USE_NAME | BT_LE_ADV_OPT_ONE_TIME;
    /*Get mode, 0:General discoverable,  1:non discoverable, 2:limit discoverable*/
    bt_le_adv_start(&param,ibeacon_data, ARRAY_SIZE(ibeacon_data),NULL,0);
    bt_set_name(IBEACON_NAME);
}

/*BLE ibeacon init*/
void ble_ibeacon_init(void)
{               
    printf("ble_controller_init\r\n");                                         
    ble_controller_init(configMAX_PRIORITIES - 1); //ble协议栈初始化
    printf("hci_driver_init\r\n");
    hci_driver_init();//初始化驱动
    printf("bt_enable\r\n");
    bt_enable(NULL);
    ble_start_advertise();//开启广播
}

static void app_init_thread(void *param)
{
    vTaskDelay(10 / portTICK_RATE_MS);
    ble_ibeacon_init();
    vTaskDelete(NULL);
}

static void app_init_entry(void)
{
    if(xTaskCreate(app_init_thread, ((const char*)"app_init"), 1024*6, NULL, tskIDLE_PRIORITY + 3 + PRIORITIE_OFFSET, NULL) != pdPASS)
    printf("\n\r%s xTaskCreate(init_thread) failed", __FUNCTION__);
}

static void ble_loop_proc(void *pvParameters)
{
    app_init_entry();
    vTaskDelete(NULL);
}

void main(void)
{
    bl_uart_init(0, 16, 7, 255, 255, 115200);//set uart baud 115200
    printf("AXK BLE IBEACON\r\n");//log
    bl_sys_init(); //if use ble,must init
    xTaskCreate(ble_loop_proc,  (char*)"ibeacon", 1024, NULL, 15, NULL);
}

---

FAQ & Troubleshooting

⚠️ What's the difference between BLE and regular Bluetooth
Cause: both are called Bluetooth, but serve different purposes
Fix: BLE (low-energy Bluetooth) saves power, connects fast and only carries small data — suited to sensors/wristbands; classic Bluetooth is power-hungry and suited to audio and file transfer. The Ai-WB2 has BLE 4.2 built in

⚠️ The phone can't find the board's advertised device
Cause: advertising not started, distance too far, or the phone's Bluetooth/location permission is off
Fix: confirm the program calls bt_le_adv_start(); Android phones need the "location permission" to scan BLE devices; move the phone close to the board (within 0.5~5 m) and scan again

⚠️ Is BLE fast? How much can it send at once
Cause: BLE sacrifices speed for power saving
Fix: BLE 4.2's theoretical rate is about 1 Mbps, and a single "notification" is usually tens of bytes — suited to small data like sensor readings and remote commands; use Wi-Fi for large files

⚠️ Should my device be a master or a slave
Cause: the role depends on "who takes the initiative"
Fix: be the master if you need to actively connect to others (like a phone app connecting to a wristband); be the slave if you need to keep advertising and wait for others (like wristbands, sensors, electronic shelf labels)

⚠️ What is provisioning? Why provision over Bluetooth
Cause: devices have no screen or keyboard, so they can't type in a Wi-Fi password
Fix: provisioning is the process of sending the Wi-Fi account/password to a device — like enrolling a fingerprint on a door lock. Provisioning over BLE needs no extra hardware: a phone app connects to the device and "hands over" the password; that's exactly what the blufi Provisioning tutorial in this series does

Self-Check

This page is a concept chapter — no need to compile or run code. You pass if you can explain the five concepts in your own words — "master/slave, advertising, GATT (services/characteristics), UUID, MAC address" — and name what each of the 4 hands-on pages in this series does.