332 lines
10 KiB
C
332 lines
10 KiB
C
/** @file
|
|
* @brief Bluetooth subsystem core APIs.
|
|
*/
|
|
|
|
/*
|
|
* Copyright (c) 2015 Intel Corporation
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
#ifndef __BT_BLUETOOTH_H
|
|
#define __BT_BLUETOOTH_H
|
|
|
|
#include <stdbool.h>
|
|
#include <stdio.h>
|
|
#include <string.h>
|
|
|
|
#include <bluetooth/hci.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** @brief Callback for notifying that Bluetooth has been enabled.
|
|
*
|
|
* @param err zero on success or (negative) error code otherwise.
|
|
*/
|
|
typedef void (*bt_ready_cb_t)(int err);
|
|
|
|
/** @brief Enable Bluetooth
|
|
*
|
|
* Enable Bluetooth. Must be the called before any calls that
|
|
* require communication with the local Bluetooth hardware.
|
|
*
|
|
* @param cb Callback to notify completion or NULL to perform the
|
|
* enabling synchronously.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_enable(bt_ready_cb_t cb);
|
|
|
|
/* Advertising API */
|
|
|
|
/** Description of different data types that can be encoded into
|
|
* advertising data. Used to form arrays that are passed to the
|
|
* bt_le_adv_start() function.
|
|
*/
|
|
struct bt_data {
|
|
uint8_t type;
|
|
uint8_t data_len;
|
|
const uint8_t *data;
|
|
};
|
|
|
|
/** Helper to declare inline byte arrays */
|
|
#define BT_BYTES(bytes...) ((uint8_t []) { bytes })
|
|
|
|
/** Helper to declare elements of bt_data arrays */
|
|
#define BT_DATA(_type, _data, _data_len) \
|
|
{ \
|
|
.type = _type, \
|
|
.data_len = _data_len, \
|
|
.data = _data, \
|
|
}
|
|
|
|
/** Local advertising address type */
|
|
enum {
|
|
/** Use local public address for advertising */
|
|
BT_LE_ADV_ADDR_PUBLIC,
|
|
|
|
/** Use local Non-resolvable Private Address (NRPA) for advertising */
|
|
BT_LE_ADV_ADDR_NRPA,
|
|
};
|
|
|
|
/** LE Advertising Parameters. */
|
|
struct bt_le_adv_param {
|
|
/** Advertising type */
|
|
uint8_t type;
|
|
|
|
/** Which type of own address to use for advertising */
|
|
uint8_t addr_type;
|
|
|
|
/** Minimum Advertising Interval (N * 0.625) */
|
|
uint16_t interval_min;
|
|
|
|
/** Maximum Advertising Interval (N * 0.625) */
|
|
uint16_t interval_max;
|
|
};
|
|
|
|
/** Helper to declare advertising parameters inline
|
|
*
|
|
* @param _type Advertising Type
|
|
* @param _addr_type Local address type to use for advertising
|
|
* @param _int_min Minimum advertising interval
|
|
* @param _int_max Maximum advertising interval
|
|
*/
|
|
#define BT_LE_ADV_PARAM(_type, _addr_type, _int_min, _int_max) \
|
|
(&(struct bt_le_adv_param) { \
|
|
.type = (_type), \
|
|
.addr_type = (_addr_type), \
|
|
.interval_min = (_int_min), \
|
|
.interval_max = (_int_max), \
|
|
})
|
|
|
|
#define BT_LE_ADV(t) BT_LE_ADV_PARAM(t, BT_LE_ADV_ADDR_PUBLIC, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2)
|
|
|
|
/** @brief Start advertising
|
|
*
|
|
* Set advertisement data, scan response data, advertisement parameters
|
|
* and start advertising.
|
|
*
|
|
* @param param Advertising parameters.
|
|
* @param ad Data to be used in advertisement packets.
|
|
* @param ad_len Number of elements in ad
|
|
* @param sd Data to be used in scan response packets.
|
|
* @param sd_len Number of elements in sd
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_adv_start(const struct bt_le_adv_param *param,
|
|
const struct bt_data *ad, size_t ad_len,
|
|
const struct bt_data *sd, size_t sd_len);
|
|
|
|
/** @brief Stop advertising
|
|
*
|
|
* Stops ongoing advertising.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_adv_stop(void);
|
|
|
|
/** @brief Define a type allowing user to implement a function that can
|
|
* be used to get back active LE scan results.
|
|
*
|
|
* A function of this type will be called back when user application
|
|
* triggers active LE scan. The caller will populate all needed
|
|
* parameters based on data coming from scan result.
|
|
* Such function can be set by user when LE active scan API is used.
|
|
*
|
|
* @param addr Advertiser LE address and type.
|
|
* @param rssi Strength of advertiser signal.
|
|
* @param adv_type Type of advertising response from advertiser.
|
|
* @param adv_data Address of buffer containig advertiser data.
|
|
* @param len Length of advertiser data contained in buffer.
|
|
*/
|
|
typedef void bt_le_scan_cb_t(const bt_addr_le_t *addr, int8_t rssi,
|
|
uint8_t adv_type, const uint8_t *adv_data,
|
|
uint8_t len);
|
|
|
|
/** LE scan parameters */
|
|
struct bt_le_scan_param {
|
|
/** Scan type (BT_HCI_LE_SCAN_ACTIVE or BT_HCI_LE_SCAN_PASSIVE) */
|
|
uint8_t type;
|
|
|
|
/** Duplicate filtering (BT_HCI_LE_SCAN_FILTER_DUP_ENABLE or
|
|
* BT_HCI_LE_SCAN_FILTER_DUP_DISABLE)
|
|
*/
|
|
uint8_t filter_dup;
|
|
|
|
/** Scan interval (N * 0.625 ms) */
|
|
uint16_t interval;
|
|
|
|
/** Scan window (N * 0.625 ms) */
|
|
uint16_t window;
|
|
};
|
|
|
|
/** Helper to declare scan parameters inline
|
|
*
|
|
* @param _type Scan Type (BT_HCI_LE_SCAN_ACTIVE/BT_HCI_LE_SCAN_PASSIVE)
|
|
* @param _filter Filter Duplicates
|
|
* @param _interval Scan Interval (N * 0.625 ms)
|
|
* @param _window Scan Window (N * 0.625 ms)
|
|
*/
|
|
#define BT_LE_SCAN_PARAM(_type, _filter, _interval, _window) \
|
|
(&(struct bt_le_scan_param) { \
|
|
.type = (_type), \
|
|
.filter_dup = (_filter), \
|
|
.interval = (_interval), \
|
|
.window = (_window), \
|
|
})
|
|
|
|
/** Helper macro to enable active scanning to discover new devices. */
|
|
#define BT_LE_SCAN_ACTIVE BT_LE_SCAN_PARAM(BT_HCI_LE_SCAN_ACTIVE, \
|
|
BT_HCI_LE_SCAN_FILTER_DUP_ENABLE, \
|
|
BT_GAP_SCAN_FAST_INTERVAL, \
|
|
BT_GAP_SCAN_FAST_WINDOW)
|
|
|
|
/** Helper macro to enable passive scanning to discover new devices.
|
|
*
|
|
* This macro should be used if information required for device identification
|
|
* (eg UUID) are known to be placed in Advertising Data.
|
|
*/
|
|
#define BT_LE_SCAN_PASSIVE BT_LE_SCAN_PARAM(BT_HCI_LE_SCAN_PASSIVE, \
|
|
BT_HCI_LE_SCAN_FILTER_DUP_ENABLE, \
|
|
BT_GAP_SCAN_FAST_INTERVAL, \
|
|
BT_GAP_SCAN_FAST_WINDOW)
|
|
|
|
/** @brief Start (LE) scanning
|
|
*
|
|
* Start LE scanning with and provide results through the specified
|
|
* callback.
|
|
*
|
|
* @param param Scan parameters.
|
|
* @param cb Callback to notify scan results.
|
|
*
|
|
* @return Zero on success or error code otherwise, positive in case
|
|
* of protocol error or negative (POSIX) in case of stack internal error
|
|
*/
|
|
int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb);
|
|
|
|
/** @brief Stop (LE) scanning.
|
|
*
|
|
* Stops ongoing LE scanning.
|
|
*
|
|
* @return Zero on success or error code otherwise, positive in case
|
|
* of protocol error or negative (POSIX) in case of stack internal error
|
|
*/
|
|
int bt_le_scan_stop(void);
|
|
|
|
/** @def BT_ADDR_STR_LEN
|
|
*
|
|
* @brief Recommended length of user string buffer for Bluetooth address
|
|
*
|
|
* @details The recommended length guarantee the output of address
|
|
* conversion will not lose valuable information about address being
|
|
* processed.
|
|
*/
|
|
#define BT_ADDR_STR_LEN 18
|
|
|
|
/** @def BT_ADDR_LE_STR_LEN
|
|
*
|
|
* @brief Recommended length of user string buffer for Bluetooth LE address
|
|
*
|
|
* @details The recommended length guarantee the output of address
|
|
* conversion will not lose valuable information about address being
|
|
* processed.
|
|
*/
|
|
#define BT_ADDR_LE_STR_LEN 27
|
|
|
|
/** @brief Converts binary Bluetooth address to string.
|
|
*
|
|
* @param addr Address of buffer containing binary Bluetooth address.
|
|
* @param str Address of user buffer with enough room to store formatted
|
|
* string containing binary address.
|
|
* @param len Length of data to be copied to user string buffer. Refer to
|
|
* BT_ADDR_STR_LEN about recommended value.
|
|
*
|
|
* @return Number of successfully formatted bytes from binary address.
|
|
*/
|
|
static inline int bt_addr_to_str(const bt_addr_t *addr, char *str, size_t len)
|
|
{
|
|
return snprintf(str, len, "%2.2X:%2.2X:%2.2X:%2.2X:%2.2X:%2.2X",
|
|
addr->val[5], addr->val[4], addr->val[3],
|
|
addr->val[2], addr->val[1], addr->val[0]);
|
|
}
|
|
|
|
/** @brief Converts binary LE Bluetooth address to string.
|
|
*
|
|
* @param addr Address of buffer containing binary LE Bluetooth address.
|
|
* @param user_buf Address of user buffer with enough room to store
|
|
* formatted string containing binary LE address.
|
|
* @param len Length of data to be copied to user string buffer. Refer to
|
|
* BT_ADDR_LE_STR_LEN about recommended value.
|
|
*
|
|
* @return Number of successfully formatted bytes from binary address.
|
|
*/
|
|
static inline int bt_addr_le_to_str(const bt_addr_le_t *addr, char *str,
|
|
size_t len)
|
|
{
|
|
char type[7];
|
|
|
|
switch (addr->type) {
|
|
case BT_ADDR_LE_PUBLIC:
|
|
strcpy(type, "public");
|
|
break;
|
|
case BT_ADDR_LE_RANDOM:
|
|
strcpy(type, "random");
|
|
break;
|
|
default:
|
|
sprintf(type, "0x%02x", addr->type);
|
|
break;
|
|
}
|
|
|
|
return snprintf(str, len, "%2.2X:%2.2X:%2.2X:%2.2X:%2.2X:%2.2X (%s)",
|
|
addr->val[5], addr->val[4], addr->val[3],
|
|
addr->val[2], addr->val[1], addr->val[0], type);
|
|
}
|
|
|
|
#if defined(CONFIG_BLUETOOTH_BREDR)
|
|
/** @brief Enable/disable set controller in discoverable state.
|
|
*
|
|
* Allows make local controller to listen on INQUIRY SCAN channel and responds
|
|
* to devices making general inquiry. To enable this state it's mandatory
|
|
* to first be in connectable state.
|
|
*
|
|
* @param enable Value allowing/disallowing controller to become discoverable.
|
|
*
|
|
* @return Negative if fail set to requested state or requested state has been
|
|
* already set. Zero if done successfully.
|
|
*/
|
|
int bt_br_set_discoverable(bool enable);
|
|
|
|
/** @brief Enable/disable set controller in connectable state.
|
|
*
|
|
* Allows make local controller to be connectable. It means the controller
|
|
* start listen to devices requests on PAGE SCAN channel. If disabled also
|
|
* resets discoverability if was set.
|
|
*
|
|
* @param enable Value allowing/disallowing controller to be connectable.
|
|
*
|
|
* @return Negative if fail set to requested state or requested state has been
|
|
* already set. Zero if done successfully.
|
|
*/
|
|
int bt_br_set_connectable(bool enable);
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __BT_BLUETOOTH_H */
|