NimBLE Host ATT Client Reference

Introduction

The Attribute Protocol (ATT) is a mid-level protocol that all BLE devices use to exchange data. Data is exchanged when an ATT client reads or writes an attribute belonging to an ATT server. Any device that needs to send or receive data must support both the client and server functionality of the ATT protocol. The only devices which do not support ATT are the most basic ones: broadcasters and observers (i.e., beaconing devices and listening devices).

Most ATT functionality is not interesting to an application. Rather than use ATT directly, an application uses the higher level GATT profile, which sits directly above ATT in the host. NimBLE exposes the few bits of ATT functionality which are not encompassed by higher level GATT functions. This section documents the ATT functionality that the NimBLE host exposes to the application.

API

int ble_hs_is_enabled(void)

Indicates whether the host is enabled.

The host is enabled if it is starting or fully started. It is disabled if it is stopping or stopped.

Return

1 if the host is enabled; 0 if the host is disabled.

int ble_hs_synced(void)

Indicates whether the host has synchronized with the controller.

Synchronization must occur before any host procedures can be performed.

Return

1 if the host and controller are in sync; 0 if the host and controller are out of sync.

int ble_hs_start(void)

Synchronizes the host with the controller by sending a sequence of HCI commands.

This function must be called before any other host functionality is used, but it must be called after both the host and controller are initialized. Typically, the host-parent-task calls this function at the top of its task routine. This function must only be called in the host parent task. A safe alternative for starting the stack from any task is to call ble_hs_sched_start().

If the host fails to synchronize with the controller (if the controller is not fully booted, for example), the host will attempt to resynchronize every 100 ms. For this reason, an error return code is not necessarily fatal.

Return

0 on success; nonzero on error.

void ble_hs_sched_start(void)

Enqueues a host start event to the default event queue.

The actual host startup is performed in the host parent task, but using the default queue here ensures the event won’t run until the end of main() when this is called during system initialization. This allows the application to configure the host package in the meantime.

If auto-start is disabled, the application should use this function to start the BLE stack. This function can be called at any time as long as the host is stopped. When the host successfully starts, the application is notified via the ble_hs_cfg.sync_cb callback.

void ble_hs_sched_reset(int reason)

Causes the host to reset the NimBLE stack as soon as possible.

The application is notified when the reset occurs via the host reset callback.

Parameters

  • reason: The host error code that gets passed to the reset callback.

void ble_hs_evq_set(struct ble_npl_eventq *evq)

Designates the specified event queue for NimBLE host work.

By default, the host uses the default event queue and runs in the main task. This function is useful if you want the host to run in a different task.

Parameters

  • evq: The event queue to use for host work.

void ble_hs_init(void)

Initializes the NimBLE host.

This function must be called before the OS is started. The NimBLE stack requires an application task to function. One application task in particular is designated as the “host parent task”. In addition to application-specific work, the host parent task does work for NimBLE by processing events generated by the host.

int ble_hs_shutdown(int reason)

Called when the system is shutting down.

Stops the BLE host.

Return

SYSDOWN_IN_PROGRESS.

Parameters

  • reason: The reason for the shutdown. One of the HAL_RESET_[…] codes or an implementation-defined value.

BLE_HS_FOREVER
BLE_HS_CONN_HANDLE_NONE

Connection handle not present.