### Start BLE Advertisement (C)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Starts the BLE advertising process on the RN4020 module, making it discoverable by other BLE devices. It takes the advertising interval in milliseconds and a window time parameter. Dependencies include 'ble2_hw.h' and a response waiting mechanism.

```c
#include "ble2_hw.h"

void start_advertising() {
    // Start advertising with:
    // - interval: advertising interval in milliseconds
    // - window_time: total advertising window (0 = continuous)

    // Advertise every 100ms continuously
    ble2_start_advertisement(100, 0);
    while (!wait_response("AOK"));
}

void stop_advertising() {
    ble2_stop_advertising();
    while (!wait_response("AOK"));
}
```

--------------------------------

### Peripheral Write Command

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Example of writing a specific value to a handle on the peripheral device.

```text
WV,001B,01
```

--------------------------------

### Configure Peripheral Module (Module 2)

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Configures the peripheral module for BLE communication. It sets up services including custom ones, enables authentication, configures bonding, and starts advertising. Dependencies include the BLE stack. Inputs are configuration commands, and outputs are module state changes.

```AT Commands
SF,1
SS,C0000001
SR,00480000
SB,0
SP,0
PS,F1A879125950479CA5E5B6CC81CD0502
PC,855B193883E2488980B7AE58FCD0E6CA,04,05,10
PS,1802
PC,2A06,04,01
R,1
A,1388
```

--------------------------------

### bleControl Class - Central Role Example

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Demonstrates using the bleControl class to establish a BLE connection in central mode, find a specific peripheral, and perform read/write operations on remote characteristics. Includes error handling for connection and device discovery. Dependencies include blecontrol.h.

```cpp
#include "blecontrol.h"

bleControl ble(characteristics, 2);
const char targetMac[] = "001EC01D03EA";

void setup() {
    ble.setEventListener(bleEventHandler);

    // Initialize as central
    if (!ble.begin(true)) {
        return;
    }

    // Search for target device
    if (!ble.findUnboundPeripheral(targetMac)) {
        Serial.println("Device not found");
        return;
    }

    // Establish secure connection with bonding
    if (!ble.secureConnect(targetMac)) {
        Serial.println("Connection failed");
        return;
    }

    // Read remote characteristic
    byte value[20];
    byte length;
    btCharacteristic serialNum("180A", "2A25",
        btCharacteristic::READ, 20, btCharacteristic::NOTHING);

    if (ble.readRemoteCharacteristic(&serialNum, value, length)) {
        Serial.print("Serial: ");
        Serial.println((char*)value);
    }

    // Write to remote characteristic
    ble.writeRemoteCharacteristic(&alertLevel, 0x02);

    delay(5000);
    ble.disconnect();
}

void loop() {
    ble.loop();
}
```

--------------------------------

### Start Scanning for Peripherals with RN4020

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Initiates a scan for nearby Bluetooth peripherals. Requires the target device (PebbleBee) to be discoverable.

```AT Commands
F
AOK
```

--------------------------------

### Initiate Connection with Existing Bond

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Starts a connection attempt to a previously bonded PebbleBee device. The MAC address is not required as the bond information is used.

```AT Commands
E
```

--------------------------------

### bleControl Class - High-Level BLE Management (Peripheral)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Provides simplified BLE operations for peripheral use cases. It manages BLE connections, events, and characteristic operations. This example demonstrates initializing the BLE controller, setting an event listener, and writing to a local characteristic. Dependencies include blecontrol.h and btcharacteristic.h.

```cpp
#include "blecontrol.h"
#include "btcharacteristic.h"

btCharacteristic* characteristics[] = { &rfidKey, &alertLevel };
bleControl ble(characteristics, 2);

void bleEventHandler(bleControl::EVENT ev) {
    switch (ev) {
        case bleControl::EV_CONNECTION_UP:
            Serial.println("Connected!");
            break;
        case bleControl::EV_CONNECTION_DOWN:
            Serial.println("Disconnected");
            break;
        case bleControl::EV_PASSCODE_WANTED:
            Serial.println("Enter passcode on remote device");
            ble.setPasscode(123456);
            break;
        case bleControl::EV_PASSCODE_GENERATED:
            Serial.print("Passcode: ");
            Serial.println(ble.getPasscode());
            break;
    }
}

void setup() {
    Serial.begin(9600);
    ble.setEventListener(bleEventHandler);

    // Initialize as peripheral (false) or central (true)
    if (!ble.begin(false)) {
        Serial.println("BLE init failed");
        return;
    }

    // Write to local characteristic
    ble.writeLocalCharacteristic(&alertLevel, 0x01);
}

void loop() {
    ble.loop();
}
```

--------------------------------

### RN4020 Class - Arduino Interface

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Provides an object-oriented wrapper for low-level BLE2 functions using the Arduino framework. It handles initialization, device naming, feature configuration, service setup, and rebooting the RN4020 module. Dependencies include the Arduino core and btCharacteristic definitions.

```cpp
#include "rn4020.h"
#include "btcharacteristic.h"

// Pin definitions for STM32 Nucleo F103RB
// RN4020.7 (SW_WAKE) -> D3
// RN4020.12 (ACTIVE) -> D4
// RN4020.15 (HW_WAKE) -> D5
// RN4020.PWREN -> D6

rn4020 rn(Serial1, 3, 4, 5, 6);

void setup() {
    Serial.begin(9600);

    // Initialize at 2400 baud for reliability
    if (!rn.begin(2400)) {
        Serial.println("RN4020 initialization failed");
        return;
    }

    // Set device name
    rn.setBluetoothDeviceName("MyDevice");

    // Configure features (central role with authentication)
    rn.setFeatures(0x80480000);

    // Configure services (Device Info + Battery)
    rn.setServices(0xC0000000);

    // Apply settings
    rn.doReboot(2400);
}

void loop() {
    rn.loop();  // Process incoming events
}
```

--------------------------------

### Scan for BLE Peripheral Devices (C)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Initiates a scan for nearby BLE peripheral devices. This function requires the RN4020 module to be in the central role. It starts the scan with default parameters and then stops the inquiry process after a delay to collect results. Dependencies include 'ble2_hw.h', 'Delay_ms', and a response waiting mechanism.

```c
#include "ble2_hw.h"

void scan_for_devices() {
    // Start scanning with default parameters
    ble2_query_peripheral_devices(0, 0);
    while (!wait_response("AOK"));

    // Wait for scan results (format: MAC,PRIVATE,NAME,UUID,RSSI)
    // Results come as multiple lines
    Delay_ms(5000);

    // Stop scanning
    ble2_stop_inquiry_process();
    while (!wait_response("AOK"));
}
```

--------------------------------

### Get Firmware Version using ble2_display_firmware_version

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Displays the current firmware version string of the RN4020 module. This is useful for diagnostic purposes and ensuring compatibility with specific library features.

```c
#include "ble2_hw.h"

void check_firmware() {
    ble2_display_firmware_version();
}
```

--------------------------------

### Write Local Characteristic (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Writes a value to a characteristic on the local device (server role). This can be done by UUID, for example, to update the battery level, or by a specific handle.

```c
#include "ble2_hw.h"

void update_battery_level(uint8_t level) {
    char hex_value[3];
    sprintf(hex_value, "%02X", level);

    // Write by UUID
    ble2_write_server_characteristic_value_via_UUID("2A19", hex_value);
    while (!wait_response("AOK"));
}

void write_by_handle() {
    uint16_t handle = 0x0011;

    // Write hex string to characteristic
    ble2_write_server_characteristic_content(handle, "48656C6C6F");  // "Hello"
    while (!wait_response("AOK"));
}
```

--------------------------------

### Configure Central Module (Module 1)

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Sets up the central module for BLE communication. It configures server services, enables authentication, and resets the module. Dependencies include the BLE stack. Inputs are configuration commands, and outputs are module state changes.

```AT Commands
SF,1
SS,C0000000
SR,80480000
R,1
```

--------------------------------

### RN4020 Initialization

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Configures the RN4020 module hardware pins, baud rate, device name, and feature/service flags.

```APIDOC
## INITIALIZE RN4020

### Description
Initializes the RN4020 module with specific hardware pins and communication settings.

### Method
void rn.begin(long baud)

### Parameters
- **baud** (long) - Required - Communication speed (e.g., 2400).

### Request Example
```cpp
rn4020 rn(Serial1, 3, 4, 5, 6);
if (!rn.begin(2400)) { /* Handle error */ }
```
```

--------------------------------

### Initialize RN4020 Hardware Abstraction Layer

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Initializes the UART interface and the BLE2 HAL layer. This must be executed before any other library functions to ensure the module is awake and responsive.

```c
#include "ble2_hw.h"
#include "ble2_hal.h"

void setup_ble_module() {
    UART2_Init(115200);
    Delay_ms(100);
    ble2_hal_init();
    RN_WAKE = 1;
    while (!wait_response("CMD"));
}
```

--------------------------------

### Connect and Bond (Central Module)

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Establishes a connection and bonding process with a peripheral device from the central module. It handles connection, authentication, and bonding states. This requires the peripheral to be advertising. Limitations include the need to re-secure after automatic bonding.

```AT Commands
E,0,001EC01D03EA
B
```

--------------------------------

### Connect to PebbleBee with RN4020

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Establishes a connection to a specific PebbleBee device using its MAC address. This command initiates both bonding and connection procedures.

```AT Commands
E,0,0E0A14092414
AOK
```

--------------------------------

### Configure Bluetooth Services (C)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Enables standard Bluetooth GATT services on the device using a 32-bit bitmap. This function configures which services the RN4020 module will advertise and support. Dependencies include 'ble2_hw.h' and a mechanism to wait for command responses like 'wait_response'.

```c
#include "ble2_hw.h"

void configure_services() {
    // Service bitmap values (from RN4020 User Guide Table 2-6):
    // 0x80000000 - Device Information Service
    // 0x40000000 - Battery Service
    // 0x20000000 - Heart Rate Service
    // 0x10000000 - Health Thermometer Service
    // 0x00000001 - User-defined Private Service

    // Enable Battery Service only
    ble2_set_server_services(0x40000000);
    while (!wait_response("AOK"));

    // Enable multiple services: Device Info + Battery + Private
    // ble2_set_server_services(0x80000000 | 0x40000000 | 0x00000001);

    // Reboot required
    ble2_device_reboot();
    while (!wait_response("Reboot"));
}
```

--------------------------------

### List Server Services using ble2_list_server_services

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Lists all available server services, their associated characteristics, and handles. This is used for service discovery to understand the GATT profile structure of the connected device.

```c
#include "ble2_hw.h"

void list_services() {
    ble2_list_server_services();
}
```

--------------------------------

### RN4020 Module Configuration and Reset

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Commands to reset the RN4020 module to its default settings and confirm the reset.

```AT Commands
SF,1
AOK
```

--------------------------------

### Characteristic Data Handling

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Demonstrates the behavior of writing data to a characteristic and reading it back, showing how the module handles data length variations.

```text
F1A879125950479CA5E5B6CC81CD0502
855B193883E2488980B7AE58FCD0E6CA,001B,04,05
END
SHR,001B
WV,001B,0011223344556677889911
```

--------------------------------

### List Client Services (Central Module)

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Lists the GATT services and characteristics provided by the connected peripheral device from the central module. It displays service UUIDs and characteristic details. This command is used to inspect the peripheral's capabilities.

```AT Commands
LC
180A
  2A25,000E,02
  2A27,0010,02
  2A26,0012,02
  2A28,0014,02
  2A29,0016,02
  2A24,0018,02
1802
  2A06,001B,04
```

--------------------------------

### Configure Module Features via Bitmap

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Sets the operational features of the RN4020 using a 32-bit bitmap. This controls roles such as central/peripheral and auto-advertising behavior.

```c
#include "ble2_hw.h"

void configure_features() {
    ble2_set_supported_features(0x20000000);
    while (!wait_response("AOK"));
    ble2_device_reboot();
    while (!wait_response("Reboot"));
}
```

--------------------------------

### Power Management API

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

APIs for controlling the power state of the module.

```APIDOC
## Enter Dormant Mode

### Description
Places the module into ultra-low power dormant mode.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void enter_low_power_mode() {
    // Enter dormant mode - module becomes unresponsive
    // Wake by toggling power or WAKE_HW pin
    ble2_dormant_mode_enable();

    // No UART response - module is dormant
    // Set SW_WAKE low after command
    RN_WAKE = 0;
}
```

### Response
#### Success Response (200)
No UART response as the module enters dormant mode.

#### Response Example
None

## Set Transmission Power

### Description
Configures the transmission power level (requires firmware 1.20+).

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void configure_tx_power() {
    // Power levels:
    // PWR_MIN19_1dBm = 0 (-19.1 dBm, lowest)
    // PWR_MIN15_1dBm = 1
    // PWR_MIN10_9dBm = 2
    // PWR_MIN6_9dBm  = 3
    // PWR_MIN2_5dBm  = 4
    // PWR_1_6dBm     = 5
    // PWR_5_8dBm     = 6
    // PWR_7_5        = 7 (+7.5 dBm, highest)

    int8_t result = ble2_set_transmission_power(PWR_MIN19_1dBm);
    if (result == 0) {
        while (!wait_response("AOK"));
    }
}
```

### Response
#### Success Response (200)
AOK response indicates success.

#### Response Example
```json
"AOK"
```
```

--------------------------------

### Reboot RN4020 Module

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Command to reboot the RN4020 module. This action applies configuration changes and may close existing connections.

```AT Commands
R,1
```

--------------------------------

### Peripheral Connection Status (Module 2)

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Indicates the connection status of the peripheral module. It shows connection, passcode, security, and bonding states. This output is observed after a successful connection attempt from a central module.

```AT Commands
Connected
Passcode:
147139
Secured
Bonded
```

--------------------------------

### Connect to BLE Peripheral (C)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Initiates a connection to a specified BLE peripheral device using its MAC address. The function supports connecting via public or random addresses. It returns 0 on success and -1 on failure, waiting for 'AOK' and 'Connected' events. Dependencies include 'ble2_hw.h'.

```c
#include "ble2_hw.h"

int connect_to_device(const char* mac_address) {
    // Connect using public address (0) or random address (1)
    int8_t result = ble2_start_connection(PUBLIC_ADDRESS, mac_address);

    if (result == 0) {
        while (!wait_response("AOK"));

        // Wait for "Connected" event
        while (!wait_response("Connected"));

        return 0;
    }
    return -1;
}

// Usage:
// connect_to_device("001EC01D03EA");
```

--------------------------------

### Reset RN4020 Module Configuration

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Performs a factory reset on the RN4020 module. Supports partial resets to preserve specific settings or full resets to clear all configurations.

```c
#include "ble2_hw.h"

int reset_module() {
    int8_t result = ble2_reset_to_factory_default(RESET_SOME);
    if (result == 0) {
        while (!wait_response("AOK"));
        ble2_device_reboot();
        while (!wait_response("Reboot"));
        return 0;
    }
    return -1;
}

void full_reset() {
    ble2_reset_to_factory_default(RESET_ALL);
    while (!wait_response("AOK"));
    ble2_device_reboot();
}
```

--------------------------------

### Check RN4020 Connection Status

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Queries the RN4020 module to determine the current connection status. 'No Connection' indicates no active link.

```AT Commands
Q
```

--------------------------------

### Request Services from PebbleBee

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Queries the connected PebbleBee for the services it provides, including Linkloss Alert, Immediate Alert, Tx Power, Battery Service, and Device Information.

```AT Commands
LC
```

--------------------------------

### Write to IAS Characteristic

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Demonstrates how to write data to the Immediate Alert Service (IAS) characteristic using either a handle or a UUID.

```text
CHW,001B,01
CUWV,1802,01
```

--------------------------------

### Adjust PebbleBee Performance/Power Settings

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Commands to modify settings on the PebbleBee that balance performance and power consumption. The module responds with a double bleep upon successful change.

```AT Commands
CHW,000B,AB
CHW,000B,AC
CHW,000B,AD
```

--------------------------------

### Bonding and Security API

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

APIs for managing secure connections and bonding with remote devices.

```APIDOC
## Secure Connection and Bond

### Description
Initiates bonding/pairing with a connected device for secure communication.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void bond_with_device() {
    // Bond and save pairing info to NVM
    ble2_bond(SAVED);
    while (!wait_response("AOK"));

    // Wait for bonding completion events:
    // - "Passcode:" prompts for passcode entry
    // - "Secured" indicates successful bonding
}

void secure_without_bonding() {
    // Secure connection without saving bond
    ble2_bond(NOT_SAVED);
    while (!wait_response("AOK"));
}
```

### Response
#### Success Response (200)
AOK response indicates command accepted. Bonding completion indicated by "Secured" event.

#### Response Example
```json
"AOK"
"Secured"
```

## Enter Bonding Passcode

### Description
Sends the passcode during the bonding process when prompted.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void enter_passcode(unsigned long code) {
    // Enter 6-digit passcode when "Passcode:" is received
    ble2_set_passcode(code);
    // No response expected, wait for "Secured"
}

// Usage:
// enter_passcode(123456);
```

### Response
#### Success Response (200)
No direct response, wait for "Secured" event.

#### Response Example
```json
"Secured"
```

## Remove Existing Bond

### Description
Removes the stored bonding information.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void unbond_device() {
    ble2_remove_bonding();
    while (!wait_response("AOK"));
}
```

### Response
#### Success Response (200)
AOK response indicates success.

#### Response Example
```json
"AOK"
```
```

--------------------------------

### Enter Dormant Mode (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Places the BLE2 module into an ultra-low power dormant mode (typically 8.4uA). The module becomes unresponsive and can be woken by toggling power or the WAKE_HW pin.

```c
#include "ble2_hw.h"

void enter_low_power_mode() {
    // Enter dormant mode - module becomes unresponsive
    // Wake by toggling power or WAKE_HW pin
    ble2_dormant_mode_enable();

    // No UART response - module is dormant
    // Set SW_WAKE low after command
    RN_WAKE = 0;
}
```

--------------------------------

### Define Private Service UUID (C)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Creates a custom private service on the RN4020 module by setting a 128-bit UUID. This function requires clearing existing private services first and then defining the new UUID. Dependencies include 'ble2_hw.h' and a response waiting mechanism.

```c
#include "ble2_hw.h"

void create_private_service() {
    // Clear any existing private services first
    ble2_private_service_clear_all();
    while (!wait_response("AOK"));

    // Set private service UUID (128-bit, no hyphens)
    ble2_set_private_service_uuid("f1a879125950479ca5e5b6cc81cd0502");
    while (!wait_response("AOK"));
}
```

--------------------------------

### Stop RN4020 Connection Attempt

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Command to terminate an ongoing connection attempt initiated by the 'E' command.

```AT Commands
Z
AOK
```

--------------------------------

### Scan for Devices (Central Module)

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/RN4020-characteristics

Initiates a scan for nearby BLE devices from the central module. It filters for specific advertisement types and displays discovered devices. This function is only available when not connected. Limitations include only showing undirected advertisements.

```AT Commands
F
001EC01D03EA,0,RN03EA,180D|1809,-21
X
```

--------------------------------

### Read PebbleBee Information (Battery, Serial, Firmware)

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Retrieves various information from the PebbleBee, including battery level, serial number, and firmware/software revisions. Hex strings can be converted to ASCII.

```AT Commands
CHR,0014
R,4E.
CHR,0018
R,424C452D5345435552495459205441472D303031.
AOK
CHR,001A
R,4353523130317820413035.
AOK
CHR,001C
```

--------------------------------

### Set RN4020 Alert Levels for Stable Connection

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Configures the 'immediate alert' and 'link loss alert' levels to 'AA' to help maintain a stable connection with the PebbleBee. These commands are critical and timing-sensitive.

```AT Commands
CHW,000B,AA
AOK
CHW,000E,AA
AOK
```

--------------------------------

### Close RN4020 Connection

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Command to explicitly close an active connection on the RN4020 module.

```AT Commands
K
```

--------------------------------

### Set RN4020 to Central Role with Flow Control

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Configures the RN4020 to act as a central device with flow control enabled, preparing it for scanning and connecting to peripherals.

```AT Commands
SR,82000000
AOK
```

--------------------------------

### BLE Control Management

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

High-level management of BLE states, event handling, and peripheral/central role switching.

```APIDOC
## BLE CONTROL OPERATIONS

### Description
Provides methods to manage connection events, passcodes, and data exchange.

### Methods
- **ble.begin(bool isCentral)** - Initializes the BLE stack.
- **ble.writeLocalCharacteristic(btCharacteristic* c, byte val)** - Updates local data.
- **ble.secureConnect(char* mac)** - Establishes a bonded connection.

### Request Example
```cpp
ble.setEventListener(bleEventHandler);
ble.begin(false); // Initialize as peripheral
```
```

--------------------------------

### Bond Device (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Initiates bonding/pairing with a connected device for secure communication. Bonding can be saved to NVM or performed without saving. The process may involve passcode entry and completion is indicated by a 'Secured' message.

```c
#include "ble2_hw.h"

void bond_with_device() {
    // Bond and save pairing info to NVM
    ble2_bond(SAVED);
    while (!wait_response("AOK"));

    // Wait for bonding completion events:
    // - "Passcode:" prompts for passcode entry
    // - "Secured" indicates successful bonding
}

void secure_without_bonding() {
    // Secure connection without saving bond
    ble2_bond(NOT_SAVED);
    while (!wait_response("AOK"));
}
```

--------------------------------

### Write Local Characteristic

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Writes a value to a characteristic on the local device (server role) either by handle or by UUID.

```APIDOC
## Write Local Characteristic

### Description
Writes a value to a characteristic on the local device.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void update_battery_level(uint8_t level) {
    char hex_value[3];
    sprintf(hex_value, "%02X", level);

    // Write by UUID
    ble2_write_server_characteristic_value_via_UUID("2A19", hex_value);
    while (!wait_response("AOK"));
}

void write_by_handle() {
    uint16_t handle = 0x0011;

    // Write hex string to characteristic
    ble2_write_server_characteristic_content(handle, "48656C6C6F");  // "Hello"
    while (!wait_response("AOK"));
}
```

### Response
#### Success Response (200)
AOK response indicates success.

#### Response Example
```json
"AOK"
```
```

--------------------------------

### Configure Bluetooth Device Identity

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Sets the device name and Bluetooth-friendly name for the module. These names are visible to other devices during scanning.

```c
#include "ble2_hw.h"

void configure_device_identity() {
    int8_t result = ble2_set_device_name("BLE2_Click");
    if (result == 0) {
        while (!wait_response("AOK"));
    }
    ble2_set_device_bluetooth_name("BLE2Click");
    while (!wait_response("AOK"));
}
```

--------------------------------

### Unbond RN4020 Module

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Command to unbind the RN4020 module from any previously bonded devices. This is necessary to allow the module to be discovered during scanning.

```AT Commands
U
```

--------------------------------

### Retrieve Device Information using ble2_display_critical_info

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Displays comprehensive device information including MAC address, name, connection status, and bond status. This function is essential for verifying device identity and current operational state.

```c
#include "ble2_hw.h"

void get_device_info() {
    ble2_display_critical_info();
}
```

--------------------------------

### Set Transmission Power (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Configures the transmission power level for the BLE2 module, requiring firmware version 1.20 or later. Various power levels are available, from -19.1 dBm to +7.5 dBm.

```c
#include "ble2_hw.h"

void configure_tx_power() {
    // Power levels:
    // PWR_MIN19_1dBm = 0 (-19.1 dBm, lowest)
    // PWR_MIN15_1dBm = 1
    // PWR_MIN10_9dBm = 2
    // PWR_MIN6_9dBm  = 3
    // PWR_MIN2_5dBm  = 4
    // PWR_1_6dBm     = 5
    // PWR_5_8dBm     = 6
    // PWR_7_5        = 7 (+7.5 dBm, highest)

    int8_t result = ble2_set_transmission_power(PWR_MIN19_1dBm);
    if (result == 0) {
        while (!wait_response("AOK"));
    }
}
```

--------------------------------

### Add Private Characteristic (C)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Adds a custom characteristic to a previously defined private service. It allows specifying the characteristic's UUID, properties (read, write, notify, etc.), maximum data length, and security requirements (encryption, authentication). Dependencies include 'ble2_hw.h' and a response waiting mechanism. A reboot is required after adding characteristics.

```c
#include "ble2_hw.h"

void add_private_characteristic() {
    // First set up the private service
    ble2_set_private_service_uuid("f1a879125950479ca5e5b6cc81cd0502");
    while (!wait_response("AOK"));

    // Add characteristic with:
    // - UUID: 128-bit characteristic UUID
    // - Property bitmap: 0x02=Read, 0x04=WriteWithoutResp, 0x08=Write,
    //                    0x10=Notify, 0x20=Indicate
    // - Max data length: up to 20 bytes
    // - Security bitmap: 0x01=EncryptRead, 0x02=AuthRead,
    //                    0x10=EncryptWrite, 0x20=AuthWrite

    // Create a writable characteristic (5 bytes max, encrypted write)
    uint8_t result = ble2_set_private_characteristics(
        "855b193883e2488980b7ae58fcd0e6ca",  // UUID
        0x04,                                  // Write without response
        5,                                     // Max 5 bytes
        0x10                                   // Encrypted write required
    );

    if (result == 0) {
        while (!wait_response("AOK"));
    }

    // Reboot to make private services available
    ble2_device_reboot();
    while (!wait_response("Reboot"));
}
```

--------------------------------

### Check RN4020 Bond Status

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Verifies if a bond exists between the RN4020 and a specified device (PebbleBee) using its MAC address.

```AT Commands
Q,1
0E0A14092414,0
```

--------------------------------

### Stop Scanning with RN4020

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Command to cease the scanning process on the RN4020 module.

```AT Commands
X
AOK
```

--------------------------------

### Read Local Characteristic (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Reads the value of a characteristic on the local device (server role) either by handle or by UUID. The response contains the hex value of the characteristic.

```c
#include "ble2_hw.h"

void read_local_characteristic() {
    // Read by handle (obtain handle from ble2_list_server_services)
    uint16_t handle = 0x0011;  // Example handle

    ble2_read_server_characteristic_content(handle);
    // Response contains the hex value of the characteristic
}

void read_local_by_uuid() {
    // Read by UUID (for standard characteristics)
    ble2_read_server_characteristic_value_via_UUID("2A19");  // Battery Level
    // Response: hex string value
}
```

--------------------------------

### Enter Bonding Passcode (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Sends a passcode during the bonding process when prompted by 'Passcode:'. This function is used to complete secure pairing with a remote device.

```c
#include "ble2_hw.h"

void enter_passcode(unsigned long code) {
    // Enter 6-digit passcode when "Passcode:" is received
    ble2_set_passcode(code);
    // No response expected, wait for "Secured"
}

// Usage:
// enter_passcode(123456);

```

--------------------------------

### Configure UART Communication Speed

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Updates the baud rate for UART communication. A device reboot is required for the new settings to take effect.

```c
#include "ble2_hw.h"

int configure_uart_speed() {
    int8_t result = ble2_set_baud_rate(BR_115200);
    if (result == 0) {
        while (!wait_response("AOK"));
        ble2_device_reboot();
        UART2_Init(115200);
        Delay_ms(100);
        return 0;
    }
    return -1;
}
```

--------------------------------

### Define BLE Characteristics

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Defines custom BLE characteristics with specific UUIDs, properties, and security requirements.

```APIDOC
## DEFINE CHARACTERISTIC

### Description
Creates a new btCharacteristic object to represent a BLE characteristic.

### Parameters
- **serviceUUID** (string) - Required - The UUID of the parent service.
- **charUUID** (string) - Required - The UUID of the characteristic.
- **properties** (int) - Required - Property flags (READ, WRITE, etc).
- **maxLength** (int) - Required - Maximum data length.
- **security** (int) - Required - Security flags (ENCR_W, AUTH_R, etc).

### Request Example
```cpp
btCharacteristic alertLevel("1802", "2A06", btCharacteristic::WRITE_WOUT_RESP, 1, btCharacteristic::NOTHING, onAlertLevelChanged);
```
```

--------------------------------

### Disconnect BLE Connection (C)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Terminates the currently active BLE connection on the RN4020 module. This function sends the command to disconnect and waits for an 'AOK' response. Dependencies include 'ble2_hw.h'.

```c
#include "ble2_hw.h"

void disconnect_device() {
    ble2_kill_active_connection();
    while (!wait_response("AOK"));

    // Connection End event will be received
}
```

--------------------------------

### Read Local Characteristic

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Reads the value of a characteristic on the local device (server role) either by handle or by UUID.

```APIDOC
## Read Local Characteristic

### Description
Reads the value of a characteristic on the local device (server role).

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void read_local_characteristic() {
    // Read by handle (obtain handle from ble2_list_server_services)
    uint16_t handle = 0x0011;  // Example handle

    ble2_read_server_characteristic_content(handle);
    // Response contains the hex value of the characteristic
}

void read_local_by_uuid() {
    // Read by UUID (for standard characteristics)
    ble2_read_server_characteristic_value_via_UUID("2A19");  // Battery Level
    // Response: hex string value
}
```

### Response
#### Success Response (200)
Response contains the hex value of the characteristic or a hex string value if read by UUID.

#### Response Example
```json
"48656C6C6F"
```
```

--------------------------------

### Write Remote Characteristic (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Writes a value to a characteristic on a connected remote device (client role). Supports writing by handle or by UUID, with an expected 'AOK' response upon successful transmission.

```c
#include "ble2_hw.h"

void write_remote_alert_level() {
    uint16_t handle = 0x0015;

    // Write alert level (1 = mild alert)
    ble2_write_client_characteristic_content(handle, "01");
    while (!wait_response("AOK"));
}

void write_remote_by_uuid() {
    // Write using UUID
    ble2_write_characteristic_content_via_UUID("2A06", "02");  // High Alert
    while (!wait_response("AOK"));
}
```

--------------------------------

### Write Remote Characteristic

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Writes a value to a characteristic on a connected remote device (client role) either by handle or by UUID.

```APIDOC
## Write Remote Characteristic

### Description
Writes a value to a characteristic on a connected remote device.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void write_remote_alert_level() {
    uint16_t handle = 0x0015;

    // Write alert level (1 = mild alert)
    ble2_write_client_characteristic_content(handle, "01");
    while (!wait_response("AOK"));
}

void write_remote_by_uuid() {
    // Write using UUID
    ble2_write_characteristic_content_via_UUID("2A06", "02");  // High Alert
    while (!wait_response("AOK"));
}
```

### Response
#### Success Response (200)
AOK response indicates success.

#### Response Example
```json
"AOK"
```
```

--------------------------------

### btCharacteristic Class - Define BLE Characteristics

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Defines BLE characteristics for use with the Arduino API, specifying UUIDs, properties, maximum value length, and security settings. Supports custom write callbacks for handling characteristic value changes. Dependencies include the Arduino core.

```cpp
#include "btcharacteristic.h"
#include "rn4020.h"

// Callback for characteristic write events
void onAlertLevelChanged(byte* value, byte& length) {
    Serial.print("Alert level changed to: ");
    Serial.println(value[0], HEX);
}

// Define a private characteristic
btCharacteristic rfidKey(
    "f1a87912-5950-479c-a5e5-b6cc81cd0502",  // Service UUID
    "855b1938-83e2-4889-80b7-ae58fcd0e6ca",  // Characteristic UUID
    btCharacteristic::WRITE_WOUT_RESP,        // Property flags
    5,                                         // Max value length
    btCharacteristic::ENCR_W                   // Security: encrypted write
);

// Define a standard characteristic with callback
btCharacteristic alertLevel(
    "1802",                                    // Immediate Alert Service
    "2A06",                                    // Alert Level characteristic
    btCharacteristic::WRITE_WOUT_RESP,
    1,
    btCharacteristic::NOTHING,
    onAlertLevelChanged                        // Write callback
);

// Property flags: 
// READ = 0x02, WRITE_WOUT_RESP = 0x04, WRITE = 0x08, 
// NOTIFY = 0x10, INDICATE = 0x20

// Security flags:
// NOTHING = 0x00, ENCR_R = 0x01, AUTH_R = 0x02,
// ENCR_W = 0x10, AUTH_W = 0x20

```

--------------------------------

### Read PebbleBee Battery Level

Source: https://github.com/liebtrau/click_ble2_rn4020/wiki/PebbleBee-RN4020-communication

Command to read the current battery level of the PebbleBee device. The response format may vary.

```AT Commands
CHR,0014
R,4E.
AOK
```

--------------------------------

### Remove Bonding Information (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Removes existing stored bonding information for a previously paired device, effectively unpairing them. A successful operation is confirmed with an 'AOK' response.

```c
#include "ble2_hw.h"

void unbond_device() {
    ble2_remove_bonding();
    while (!wait_response("AOK"));
}
```

--------------------------------

### Read Remote Characteristic (BLE2)

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Reads a characteristic value from a connected remote device (client role). This function supports reading by handle or by UUID, with responses formatted as R,<hex_value>.

```c
#include "ble2_hw.h"

void read_remote_characteristic() {
    // Read remote characteristic by handle
    uint16_t handle = 0x0015;

    ble2_read_client_characteristic_content(handle);
    // Response format: R,<hex_value>
}

void read_remote_by_uuid() {
    // Read remote characteristic by UUID
    ble2_read_characteristic_content_via_UUID("2A25");  // Serial Number
    // Response: hex string value
}
```

--------------------------------

### Read Remote Characteristic

Source: https://context7.com/liebtrau/click_ble2_rn4020/llms.txt

Reads a characteristic value from a connected remote device (client role) either by handle or by UUID.

```APIDOC
## Read Remote Characteristic

### Description
Reads a characteristic value from a connected remote device (client role).

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "ble2_hw.h"

void read_remote_characteristic() {
    // Read remote characteristic by handle
    uint16_t handle = 0x0015;

    ble2_read_client_characteristic_content(handle);
    // Response format: R,<hex_value>
}

void read_remote_by_uuid() {
    // Read remote characteristic by UUID
    ble2_read_characteristic_content_via_UUID("2A25");  // Serial Number
    // Response: hex string value
}
```

### Response
#### Success Response (200)
Response format is R,<hex_value> or a hex string value if read by UUID.

#### Response Example
```json
"R,48656C6C6F"
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.