Skip to content

File ns_ble.h

FileList > includes-api > ns_ble.h

Go to the source code of this file

Generic BLE Wrapper. More...

  • #include "ns_ambiqsuite_harness.h"
  • #include "ns_malloc.h"
  • #include "wsf_types.h"
  • #include "wsf_buf.h"
  • #include "wsf_msg.h"
  • #include "wsf_trace.h"
  • #include "app_api.h"
  • #include "app_db.h"
  • #include "app_hw.h"
  • #include "app_ui.h"
  • #include "att_api.h"
  • #include "att_handler.h"
  • #include "bstream.h"
  • #include "dm_api.h"
  • #include "dm_handler.h"
  • #include "gatt_api.h"
  • #include "hci_api.h"
  • #include "l2c_api.h"
  • #include "l2c_handler.h"
  • #include "smp_api.h"
  • #include "smp_handler.h"
  • #include "svc_ch.h"
  • #include "svc_core.h"
  • #include "svc_dis.h"
  • #include <stdbool.h>
  • #include <string.h>
  • #include "hci_core.h"
  • #include "hci_drv_apollo.h"
  • #include "hci_drv_cooper.h"
  • #include "hci_handler.h"

Classes

Type Name
struct ns_ble_characteristic
struct ns_ble_connection_t
BLE Connection control block.
struct ns_ble_control
BLE Control block.
struct ns_ble_pool_config_t
WSF Buffer Pool Configuration.
struct ns_ble_service
BLE Service Configuration.
struct ns_ble_service_control
BLE Service control block.
struct ns_ble_uuid128_t
BLE UUID (128-bit)

Public Types

Type Name
enum @0
typedef int(* ns_ble_characteristic_notify_handler_t
typedef int(* ns_ble_characteristic_read_handler_t
typedef struct ns_ble_characteristic ns_ble_characteristic_t
typedef int(* ns_ble_characteristic_write_handler_t
typedef struct ns_ble_control ns_ble_control_t
BLE Control block.
union ns_ble_msg_t
typedef struct ns_ble_service_control ns_ble_service_control_t
BLE Service control block.
typedef void(* ns_ble_service_specific_handler_cb
typedef void(* ns_ble_service_specific_handler_init_cb
typedef void(* ns_ble_service_specific_init_cb
typedef bool(* ns_ble_service_specific_procMsg_cb
typedef struct ns_ble_service ns_ble_service_t
BLE Service Configuration.

Public Attributes

Type Name
const ns_core_api_t ns_ble_V0_0_1
const ns_core_api_t ns_ble_current_version
const ns_core_api_t ns_ble_oldest_supported_version

Public Functions

Type Name
int ns_ble_add_characteristic (ns_ble_service_t * s, ns_ble_characteristic_t * c)
Add a characteristic to a service. This function should be called after all characteristics have been defined using ns_ble_create_characteristic.
int ns_ble_char2uuid (const char uuidString, ns_ble_uuid128_t * uuid128)
Helper function to convert a 16-byte UUID string to a 128-bit UUID byte array. UUID string must be exactly 16 characters long and only contain hex characters.
int ns_ble_create_characteristic (ns_ble_characteristic_t * c, char const * uuidString, void * applicationValue, uint16_t valueLength, uint16_t properties, ns_ble_characteristic_read_handler_t readHandlerCb, ns_ble_characteristic_write_handler_t writeHandlerCb, ns_ble_characteristic_notify_handler_t notifyHandlerCb, uint16_t periodMs, uint8_t async, uint16_t * attributeCount)
Define a characteristic for subsequent addition to a service.
int ns_ble_create_service (ns_ble_service_t * s)
Create a BLE service based on the given configuration.
void ns_ble_pre_init (void)
Call this function from the setup_task, prior to creating the RadioTask All this does is set up NVIC priorities.
void ns_ble_send_value (ns_ble_characteristic_t * c, attEvt_t * pMsg)
int ns_ble_set_tx_power (txPowerLevel_t power)
Function to set the BLE TX power.
int ns_ble_start_service (ns_ble_service_t * s)
Invoked by RadioTask to start the service. This function should be called after all characteristics have been added.

Macros

Type Name
define NS_BLE_API_ID 0xCA0008
define NS_BLE_ATT_UUID_BUILD (part) NS_BLE_ATT_UUID_POSTAMBLE, UINT16_TO_BYTES(part), NS_BLE_ATT_UUID_PREAMBLE
define NS_BLE_ATT_UUID_POSTAMBLE 0x14, 0x12, 0x8a, 0x76, 0x04, 0xd1, 0x6c, 0x4f, 0x7e, 0x53
define NS_BLE_ATT_UUID_PREAMBLE 0x00, 0x00, 0xb1, 0x19
define NS_BLE_CCC_DECL (_prop)
define NS_BLE_CHAR_DECL (_char)
define NS_BLE_CHAR_VAL (_prop, _settings, _permissions)
define NS_BLE_CONN_MAX 1
define NS_BLE_CURRENT_VERSION NS_BLE_V0_0_1
define NS_BLE_DEFAULT_MALLOC_K 8
define NS_BLE_MAX_SERVICES 1
define NS_BLE_OLDEST_SUPPORTED_VERSION NS_BLE_V0_0_1
define NS_BLE_V0_0_1 { .major = 0, .minor = 0, .revision = 1 }

Detailed Description

Author:

Ambiq Team

Version:

0.1

Date:

2023-06-08

Copyright:

Copyright (c) 2023

Public Types Documentation

enum @0

enum @0 {
    NS_BLE_READ = 1,
    NS_BLE_WRITE = 2,
    NS_BLE_NOTIFY = 4,
    NS_BLE_PROP_MAX
};

typedef ns_ble_characteristic_notify_handler_t

typedef int(* ns_ble_characteristic_notify_handler_t) (ns_ble_service_t *, ns_ble_characteristic_t *);

typedef ns_ble_characteristic_read_handler_t

typedef int(* ns_ble_characteristic_read_handler_t) (ns_ble_service_t *, ns_ble_characteristic_t *, void *);

typedef ns_ble_characteristic_t

typedef struct ns_ble_characteristic ns_ble_characteristic_t;

typedef ns_ble_characteristic_write_handler_t

typedef int(* ns_ble_characteristic_write_handler_t) (ns_ble_service_t *, ns_ble_characteristic_t *, void *);

typedef ns_ble_control_t

typedef struct ns_ble_control ns_ble_control_t;

union ns_ble_msg_t

typedef ns_ble_service_control_t

typedef struct ns_ble_service_control ns_ble_service_control_t;

typedef ns_ble_service_specific_handler_cb

typedef void(* ns_ble_service_specific_handler_cb) (wsfEventMask_t event, wsfMsgHdr_t *pMsg);

typedef ns_ble_service_specific_handler_init_cb

typedef void(* ns_ble_service_specific_handler_init_cb) (wsfHandlerId_t handlerId);

typedef ns_ble_service_specific_init_cb

typedef void(* ns_ble_service_specific_init_cb) (wsfHandlerId_t handlerId, struct ns_ble_control *generic_cfg, struct ns_ble_service_control *specific_cfg);

typedef ns_ble_service_specific_procMsg_cb

typedef bool(* ns_ble_service_specific_procMsg_cb) (ns_ble_msg_t *pMsg);

typedef ns_ble_service_t

typedef struct ns_ble_service ns_ble_service_t;

Public Attributes Documentation

variable ns_ble_V0_0_1

const ns_core_api_t ns_ble_V0_0_1;

variable ns_ble_current_version

const ns_core_api_t ns_ble_current_version;

variable ns_ble_oldest_supported_version

const ns_core_api_t ns_ble_oldest_supported_version;

Public Functions Documentation

function ns_ble_add_characteristic

Add a characteristic to a service. This function should be called after all characteristics have been defined using ns_ble_create_characteristic. 

int ns_ble_add_characteristic (
    ns_ble_service_t * s,
    ns_ble_characteristic_t * c
)

Parameters:

  • s - a pointer to the service to which the characteristic should be added
  • c - a pointer to the characteristic to be added

Returns:

int

function ns_ble_char2uuid

Helper function to convert a 16-byte UUID string to a 128-bit UUID byte array. UUID string must be exactly 16 characters long and only contain hex characters. 

int ns_ble_char2uuid (
    const char uuidString,
    ns_ble_uuid128_t * uuid128
)

Parameters:

  • uuidString - a 16-byte UUID string
  • uuid128 - a pointer to a 128-bit UUID byte array (uuid128.array)

Returns:

int

function ns_ble_create_characteristic

Define a characteristic for subsequent addition to a service. 

int ns_ble_create_characteristic (
    ns_ble_characteristic_t * c,
    char const * uuidString,
    void * applicationValue,
    uint16_t valueLength,
    uint16_t properties,
    ns_ble_characteristic_read_handler_t readHandlerCb,
    ns_ble_characteristic_write_handler_t writeHandlerCb,
    ns_ble_characteristic_notify_handler_t notifyHandlerCb,
    uint16_t periodMs,
    uint8_t async,
    uint16_t * attributeCount
)

Parameters:

  • c - config struct, populated by this function
  • uuidString - a 16-byte UUID string
  • applicationValue - a pointer to the application's value store
  • valueLength - the length of the value store, in bytes
  • properties - a bitmask of properties for the characteristic, from the enum above
  • readHandlerCb - a callback function for read requests if the characteristic is readable
  • writeHandlerCb - a callback function for write requests if the characteristic is writable
  • notifyHandlerCb - a callback function for notify requests if the characteristic is "subscribe-able"
  • periodMs - the period of the notify timer, in milliseconds
  • attributeCount - a pointer to the service's attribute count. This is incremented by the function.

Returns:

int

function ns_ble_create_service

Create a BLE service based on the given configuration. 

int ns_ble_create_service (
    ns_ble_service_t * s
)

Parameters:

  • s - a pointer to a service configuration struct. Relevant fields are:
  • uuid128: a 128-bit UUID for the service
  • name: a string name for the service, up to 31 characters
  • nameLen: the length of the name string
  • baseHandle: the first handle ID of the service. This is used by BLE to identify attributes of the service
  • numAttributes: keeps track of the number of attributes in the service. Initialize to 0.
  • poolConfig: a pointer to a WSF pool configuration struct.

Returns:

int

function ns_ble_pre_init

void ns_ble_pre_init (
    void
)

function ns_ble_send_value

void ns_ble_send_value (
    ns_ble_characteristic_t * c,
    attEvt_t * pMsg
)

function ns_ble_set_tx_power

Function to set the BLE TX power. 

int ns_ble_set_tx_power (
    txPowerLevel_t power
)

Parameters:

  • power - tx power level in dBm.

Returns:

bool

function ns_ble_start_service

Invoked by RadioTask to start the service. This function should be called after all characteristics have been added. 

int ns_ble_start_service (
    ns_ble_service_t * s
)

Parameters:

  • s - a pointer to the service to be started

Returns:

int

Macro Definition Documentation

define NS_BLE_API_ID

#define NS_BLE_API_ID 0xCA0008

define NS_BLE_ATT_UUID_BUILD

#define NS_BLE_ATT_UUID_BUILD (
    part
) NS_BLE_ATT_UUID_POSTAMBLE, UINT16_TO_BYTES(part), NS_BLE_ATT_UUID_PREAMBLE

define NS_BLE_ATT_UUID_POSTAMBLE

#define NS_BLE_ATT_UUID_POSTAMBLE 0x14, 0x12, 0x8a, 0x76, 0x04, 0xd1, 0x6c, 0x4f, 0x7e, 0x53

define NS_BLE_ATT_UUID_PREAMBLE

#define NS_BLE_ATT_UUID_PREAMBLE 0x00, 0x00, 0xb1, 0x19

Base UUID: 00002760-08C2-11E1-9073-0E8AC72EXXXX

Base UUID: 00002760-08C2-11E1-9073-0E8AC72EXXXX

define NS_BLE_CCC_DECL

#define NS_BLE_CCC_DECL (
    _prop
) {                                                                                          \
            .pUuid = attCliChCfgUuid, .pValue = (uint8_t *)_prop##ChCcc,                           \
            .pLen = (uint16_t *)&_prop##ChCccLen, .maxLen = sizeof(_prop##ChCcc),                  \
            .settings = ATTS_SET_CCC, .permissions = (ATTS_PERMIT_READ | ATTS_PERMIT_WRITE),       \
        }

define NS_BLE_CHAR_DECL

#define NS_BLE_CHAR_DECL (
    _char
) {                                                                                          \
            .pUuid = attChUuid, .pValue = (uint8_t *)_char##Ch, .pLen = (uint16_t *)&_char##ChLen, \
            .maxLen = sizeof(_char##Ch), .settings = 0, .permissions = ATTS_PERMIT_READ,           \
        }

define NS_BLE_CHAR_VAL

#define NS_BLE_CHAR_VAL (
    _prop,
    _settings,
    _permissions
) {                                                                                          \
            .pUuid = _prop##ChUuid, .pValue = (uint8_t *)_prop##ChData,                            \
            .pLen = (uint16_t *)&_prop##ChDataLen, .maxLen = sizeof(_prop##ChData),                \
            .settings = _settings, .permissions = _permissions,                                    \
        }

define NS_BLE_CONN_MAX

#define NS_BLE_CONN_MAX 1

define NS_BLE_CURRENT_VERSION

#define NS_BLE_CURRENT_VERSION NS_BLE_V0_0_1

define NS_BLE_DEFAULT_MALLOC_K

#define NS_BLE_DEFAULT_MALLOC_K 8

define NS_BLE_MAX_SERVICES

#define NS_BLE_MAX_SERVICES 1

define NS_BLE_OLDEST_SUPPORTED_VERSION

#define NS_BLE_OLDEST_SUPPORTED_VERSION NS_BLE_V0_0_1

define NS_BLE_V0_0_1

#define NS_BLE_V0_0_1 { .major = 0, .minor = 0, .revision = 1 }

The documentation for this class was generated from the following file neuralSPOT/neuralspot/ns-ble/includes-api/ns_ble.h