BLE Host API reference.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/e0b9d12e Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/e0b9d12e Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/e0b9d12e Branch: refs/heads/develop Commit: e0b9d12e6ce4885184f866d190c972c23689e161 Parents: a205cf2 Author: Christopher Collins <ccoll...@apache.org> Authored: Thu Jul 7 18:08:29 2016 -0700 Committer: Christopher Collins <ccoll...@apache.org> Committed: Thu Jul 7 18:08:29 2016 -0700 ---------------------------------------------------------------------- docs/network/ble/ble_hs/ble_gap/ble_gap.md | 36 +++ .../ble_hs/ble_gap/definitions/ble_gap_defs.md | 318 +++++++++++++++++++ .../ble_gap/functions/ble_gap_adv_active.md | 21 ++ .../functions/ble_gap_adv_rsp_set_fields.md | 25 ++ .../ble_gap/functions/ble_gap_adv_set_fields.md | 25 ++ .../ble_gap/functions/ble_gap_adv_start.md | 32 ++ .../ble_gap/functions/ble_gap_adv_stop.md | 22 ++ .../ble_gap/functions/ble_gap_conn_active.md | 21 ++ .../ble_gap/functions/ble_gap_conn_cancel.md | 21 ++ .../ble_gap/functions/ble_gap_conn_find.md | 24 ++ .../ble_hs/ble_gap/functions/ble_gap_connect.md | 32 ++ .../ble_hs/ble_gap/functions/ble_gap_disc.md | 29 ++ .../ble_gap/functions/ble_gap_disc_active.md | 21 ++ .../ble_gap/functions/ble_gap_disc_cancel.md | 22 ++ .../functions/ble_gap_security_initiate.md | 25 ++ .../ble_gap/functions/ble_gap_terminate.md | 25 ++ .../ble_gap/functions/ble_gap_update_params.md | 27 ++ .../ble_hs/ble_gap/functions/ble_gap_wl_set.md | 25 ++ docs/network/ble/ble_hs/ble_gattc/ble_gattc.md | 37 +++ .../ble_gattc/definitions/ble_gattc_defs.md | 82 +++++ .../functions/ble_gattc_disc_all_chrs.md | 29 ++ .../functions/ble_gattc_disc_all_dscs.md | 29 ++ .../functions/ble_gattc_disc_all_svcs.md | 23 ++ .../functions/ble_gattc_disc_chrs_by_uuid.md | 30 ++ .../functions/ble_gattc_disc_svc_by_uuid.md | 27 ++ .../functions/ble_gattc_exchange_mtu.md | 25 ++ .../functions/ble_gattc_find_inc_svcs.md | 29 ++ .../ble_gattc/functions/ble_gattc_notify.md | 24 ++ .../functions/ble_gattc_notify_custom.md | 27 ++ .../ble_gattc/functions/ble_gattc_read.md | 27 ++ .../functions/ble_gattc_read_by_uuid.md | 29 ++ .../ble_gattc/functions/ble_gattc_read_long.md | 27 ++ .../ble_gattc/functions/ble_gattc_read_mult.md | 29 ++ .../ble_gattc/functions/ble_gattc_write.md | 29 ++ .../ble_gattc/functions/ble_gattc_write_long.md | 30 ++ .../functions/ble_gattc_write_no_rsp.md | 27 ++ .../functions/ble_gattc_write_reliable.md | 27 ++ docs/network/ble/ble_hs/ble_gatts/ble_gatts.md | 24 ++ .../ble_gatts/definitions/ble_gatts_defs.md | 187 +++++++++++ .../ble_gatts/functions/ble_gatts_find_chr.md | 27 ++ .../ble_gatts/functions/ble_gatts_find_dsc.md | 27 ++ .../ble_gatts/functions/ble_gatts_find_svc.md | 24 ++ .../functions/ble_gatts_register_svcs.md | 27 ++ docs/network/ble/ble_hs/ble_hs.md | 22 ++ docs/network/ble/ble_hs/ble_hs_id/ble_hs_id.md | 42 +++ .../ble_hs_id/functions/ble_hs_id_copy_addr.md | 28 ++ .../ble_hs_id/functions/ble_hs_id_gen_rnd.md | 24 ++ .../ble_hs_id/functions/ble_hs_id_set_rnd.md | 23 ++ docs/network/ble/ble_hs/ble_hs_return_codes.md | 290 +++++++++++++++++ .../ble/ble_hs/init/definitions/init_defs.md | 147 +++++++++ .../ble/ble_hs/init/functions/ble_hs_init.md | 24 ++ .../ble/ble_hs/init/functions/ble_hs_start.md | 21 ++ docs/network/ble/ble_hs/init/init.md | 22 ++ .../functions/ble_eddystone_set_adv_data_uid.md | 26 ++ .../functions/ble_eddystone_set_adv_data_url.md | 31 ++ .../other/functions/ble_ibeacon_set_adv_data.md | 26 ++ .../other/functions/ble_uuid_128_to_16.md | 23 ++ .../other/functions/ble_uuid_16_to_128.md | 24 ++ docs/network/ble/ble_hs/other/other.md | 25 ++ mkdocs.yml | 84 +++++ 60 files changed, 2536 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/ble_gap.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/ble_gap.md b/docs/network/ble/ble_hs/ble_gap/ble_gap.md new file mode 100644 index 0000000..bcc142f --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/ble_gap.md @@ -0,0 +1,36 @@ +## <font color="F2853F" style="font-size:24pt">NimBLE Host GAP Reference</font> + +### Introduction + +The Generic Access Profile (GAP) is responsible for all connecting, advertising, scanning, and connection updating operations. + +### Header + +```c +#include "host/ble_hs.h" +``` + +### Definitions + +[BLE host GAP definitions](definitions/ble_gap_defs.md) + +### Functions + +| Function | Description | +|----------|-------------| +| [ble_gap_adv_active](functions/ble_gap_adv_active.md) | Indicates whether an advertisement procedure is currently in progress. | +| [ble_gap_adv_rsp_set_fields](functions/ble_gap_adv_rsp_set_fields.md) | Configures the data to include in subsequent scan responses. | +| [ble_gap_adv_set_fields](functions/ble_gap_adv_set_fields.md) | Configures the data to include in subsequent advertisements. | +| [ble_gap_adv_start](functions/ble_gap_adv_start.md) | Initiates advertising. | +| [ble_gap_adv_stop](functions/ble_gap_adv_stop.md) | Stops the currently-active advertising procedure. | +| [ble_gap_conn_active](functions/ble_gap_conn_active.md) | Indicates whether a connect procedure is currently in progress. | +| [ble_gap_conn_cancel](functions/ble_gap_conn_cancel.md) | Aborts a connect procedure in progress. | +| [ble_gap_conn_find](functions/ble_gap_conn_find.md) | Searches for a connection with the specified handle. | +| [ble_gap_connect](functions/ble_gap_connect.md) | Initiates a connect procedure. | +| [ble_gap_disc](functions/ble_gap_disc.md) | Performs the Limited or General Discovery Procedures. | +| [ble_gap_disc_active](functions/ble_gap_disc_active.md) | Indicates whether a discovery procedure is currently in progress. | +| [ble_gap_disc_cancel](functions/ble_gap_disc_cancel.md) | Cancels the discovery procedure currently in progress. | +| [ble_gap_security_initiate](functions/ble_gap_security_initiate.md) | Initiates the GAP encryption procedure. | +| [ble_gap_terminate](functions/ble_gap_terminate.md) | Terminates an established connection. | +| [ble_gap_update_params](functions/ble_gap_update_params.md) | Initiates a connection parameter update procedure. | + [ble_gap_wl_set](functions/ble_gap_wl_set.md) | Overwrites the controller's white list with the specified contents. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs.md b/docs/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs.md new file mode 100644 index 0000000..8c6b6b3 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs.md @@ -0,0 +1,318 @@ +## <font color="#F2853F" style="font-size:24pt">GAP events</font> + +```c +typedef int ble_gap_event_fn(struct ble_gap_event *ctxt, void *arg); +``` + +```c +#define BLE_GAP_EVENT_CONNECT 0 +#define BLE_GAP_EVENT_DISCONNECT 1 +#define BLE_GAP_EVENT_CONN_CANCEL 2 +#define BLE_GAP_EVENT_CONN_UPDATE 3 +#define BLE_GAP_EVENT_CONN_UPDATE_REQ 4 +#define BLE_GAP_EVENT_L2CAP_UPDATE_REQ 5 +#define BLE_GAP_EVENT_TERM_FAILURE 6 +#define BLE_GAP_EVENT_DISC 7 +#define BLE_GAP_EVENT_DISC_COMPLETE 8 +#define BLE_GAP_EVENT_ADV_COMPLETE 9 +#define BLE_GAP_EVENT_ENC_CHANGE 10 +#define BLE_GAP_EVENT_PASSKEY_ACTION 11 +#define BLE_GAP_EVENT_NOTIFY 12 +``` + +```c + +/** + * Represents a GAP-related event. When such an event occurs, the host + * notifies the application by passing an instance of this structure to an + * application-specified callback. + */ +struct ble_gap_event { + /** + * Indicates the type of GAP event that occurred. This is one of the + * BLE_GAP_EVENT codes. + */ + uint8_t type; + + /** + * A discriminated union containing additional details concerning the GAP + * event. The 'type' field indicates which member of the union is valid. + */ + union { + /** + * Represents a connection attempt. Valid for the following event + * types: + * o BLE_GAP_EVENT_CONNECT + */ + struct { + /** + * The status of the connection attempt; + * o 0: the connection was successfully established. + * o BLE host error code: the connection attempt failed for + * the specified reason. + */ + int status; + + /** + * Information about the established connection. Only valid on + * success. + */ + struct ble_gap_conn_desc conn; + } connect; + + /** + * Represents a terminated connection. Valid for the following event + * types: + * o BLE_GAP_EVENT_DISCONNECT + */ + struct { + /** + * A BLE host return code indicating the reason for the + * disconnect. + */ + int reason; + + /** Information about the terminated connection. */ + struct ble_gap_conn_desc conn; + } disconnect; + + /** + * Represents an advertising report received during a discovery + * procedure. Valid for the following event types: + * o BLE_GAP_EVENT_DISC + */ + struct ble_gap_disc_desc disc; + + /** + * Represents an attempt to update a connection's parameters. Valid + * for the following event types: + * o BLE_GAP_EVENT_CONN_UPDATE + */ + struct { + /** + * The result of the connection update attempt; + * o 0: the connection was successfully updated. + * o BLE host error code: the connection update attempt failed + * for the specified reason. + */ + int status; + + /** + * Information about the relevant connection. If the connection + * update attempt was successful, this descriptor contains the + * updated parameters. + */ + struct ble_gap_conn_desc conn; + } conn_update; + + /** + * Represents a peer's request to update the connection parameters. + * This event is generated when a peer performs any of the following + * procedures: + * o L2CAP Connection Parameter Update Procedure + * o Link-Layer Connection Parameters Request Procedure + * + * Valid for the following event types: + * o BLE_GAP_EVENT_L2CAP_UPDATE_REQ + * o BLE_GAP_EVENT_CONN_UPDATE_REQ + * + */ + struct { + /** + * Indicates the connection parameters that the peer would like to + * use. + */ + const struct ble_gap_upd_params *peer_params; + + /** + * Indicates the connection parameters that the local device would + * like to use. The application callback should fill this in. By + * default, this struct contains the requested parameters (i.e., + * it is a copy of 'peer_params'). + */ + struct ble_gap_upd_params *self_params; + + /** Information about the relevant connection. */ + struct ble_gap_conn_desc conn; + } conn_update_req; + + /** + * Represents a failed attempt to terminate an established connection. + * Valid for the following event types: + * o BLE_GAP_EVENT_TERM_FAILURE + */ + struct { + /** + * A BLE host return code indicating the reason for the failure. + */ + int status; + + /** Information about the relevant connection. */ + struct ble_gap_conn_desc conn; + } term_failure; + + /** + * Represents an attempt to change the encrypted state of a + * connection. Valid for the following event types: + * o BLE_GAP_EVENT_ENC_CHANGE + */ + struct { + /** + * Indicates the result of the encryption state change attempt; + * o 0: the encrypted state was successfully updated; + * o BLE host error code: the encryption state change attempt + * failed for the specified reason. + */ + int status; + + /** + * Information about the relevant connection. If the encryption + * state change attempt was successful, this descriptor reflects + * the updated state. + */ + struct ble_gap_conn_desc conn; + } enc_change; + + /** + * Represents a passkey query needed to complete a pairing procedure. + * Valid for the following event types: + * o BLE_GAP_EVENT_PASSKEY_ACTION + */ + struct { + /** Contains details about the passkey query. */ + struct ble_gap_passkey_params params; + + /** Information about the relevant connection. */ + struct ble_gap_conn_desc conn; + } passkey; + + /** + * Represents a received ATT notification or indication. + * Valid for the following event types: + * o BLE_GAP_EVENT_NOTIFY + */ + struct { + /** The handle of the relevant ATT attribute. */ + uint16_t attr_handle; + + /** The contents of the notification or indication. */ + void *attr_data; + + /** The number of data bytes contained in the message. */ + uint16_t attr_len; + + /** Information about the relevant connection. */ + struct ble_gap_conn_desc conn; + + /** + * Whether the received command is a notification or an + * indication; + * o 0: Notification; + * o 1: Indication. + */ + unsigned indication:1; + } notify; + }; +}; +``` + +```c +struct ble_gap_sec_state { + unsigned encrypted:1; + unsigned authenticated:1; + unsigned bonded:1; +}; +``` + +```c +/** + * @param discoverable_mode One of the following constants: + * o BLE_GAP_DISC_MODE_NON + * (non-discoverable; 3.C.9.2.2). + * o BLE_GAP_DISC_MODE_LTD + * (limited-discoverable; 3.C.9.2.3). + * o BLE_GAP_DISC_MODE_GEN + * (general-discoverable; 3.C.9.2.4). + * @param connectable_mode One of the following constants: + * o BLE_GAP_CONN_MODE_NON + * (non-connectable; 3.C.9.3.2). + * o BLE_GAP_CONN_MODE_DIR + * (directed-connectable; 3.C.9.3.3). + * o BLE_GAP_CONN_MODE_UND + * (undirected-connectable; 3.C.9.3.4). + */ +struct ble_gap_adv_params { + /*** Mandatory fields. */ + uint8_t conn_mode; + uint8_t disc_mode; + + /*** Optional fields; assign 0 to make the stack calculate them. */ + uint16_t itvl_min; + uint16_t itvl_max; + uint8_t channel_map; + uint8_t filter_policy; + uint8_t high_duty_cycle:1; +}; +``` + +```c +struct ble_gap_conn_desc { + struct ble_gap_sec_state sec_state; + uint8_t peer_ota_addr[6]; + uint8_t peer_id_addr[6]; + uint8_t our_id_addr[6]; + uint8_t our_ota_addr[6]; + uint16_t conn_handle; + uint16_t conn_itvl; + uint16_t conn_latency; + uint16_t supervision_timeout; + uint8_t peer_ota_addr_type; + uint8_t peer_id_addr_type; + uint8_t our_id_addr_type; + uint8_t our_ota_addr_type; + uint8_t role; + uint8_t master_clock_accuracy; +}; +``` + +```c +struct ble_gap_conn_params { + uint16_t scan_itvl; + uint16_t scan_window; + uint16_t itvl_min; + uint16_t itvl_max; + uint16_t latency; + uint16_t supervision_timeout; + uint16_t min_ce_len; + uint16_t max_ce_len; +}; +``` + +```c +struct ble_gap_disc_params { + uint16_t itvl; + uint16_t window; + uint8_t filter_policy; + uint8_t limited:1; + uint8_t passive:1; + uint8_t filter_duplicates:1; +}; +``` + +```c +struct ble_gap_upd_params { + uint16_t itvl_min; + uint16_t itvl_max; + uint16_t latency; + uint16_t supervision_timeout; + uint16_t min_ce_len; + uint16_t max_ce_len; +}; +``` + +```c +struct ble_gap_passkey_params { + uint8_t action; + uint32_t numcmp; +}; +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active.md new file mode 100644 index 0000000..df103ab --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active.md @@ -0,0 +1,21 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_adv\_active</font> + +```c +int +ble_gap_adv_active(void) +``` + +### Description + +Indicates whether an advertisement procedure is currently in progress. + +### Parameters + +None + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | No advertisement procedure in progress. | +| 1 | Advertisement procedure in progress. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields.md new file mode 100644 index 0000000..4333457 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields.md @@ -0,0 +1,25 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_adv\_rsp\_set\_fields</font> + +```c +int +ble_gap_adv_rsp_set_fields(const struct ble_hs_adv_fields *rsp_fields) +``` + +### Description + +Configures the data to include in subsequent scan responses. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| adv\_fields | Specifies the scan response data. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_EBUSY | Advertising is in progress. | +| BLE\_HS\_EMSGSIZE | The specified data is too large to fit in an advertisement. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields.md new file mode 100644 index 0000000..74d6d66 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields.md @@ -0,0 +1,25 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_adv\_set\_fields</font> + +```c +int +ble_gap_adv_set_fields(const struct ble_hs_adv_fields *adv_fields) +``` + +### Description + +Configures the data to include in subsequent advertisements. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| adv\_fields | Specifies the advertisement data. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_EBUSY | Advertising is in progress. | +| BLE\_HS\_EMSGSIZE | The specified data is too large to fit in an advertisement. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start.md new file mode 100644 index 0000000..ce6bf5e --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start.md @@ -0,0 +1,32 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_adv\_start</font> + +```c +int +ble_gap_adv_start(uint8_t own_addr_type, uint8_t peer_addr_type, + const uint8_t *peer_addr, int32_t duration_ms, + const struct ble_gap_adv_params *adv_params, + ble_gap_event_fn *cb, void *cb_arg) +``` + +### Description + +Initiates advertising. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| own\_addr\_type | The type of address the stack should use for itself. Valid values are: <ul><li>BLE\_ADDR\_TYPE\_PUBLIC</li> <li>BLE\_ADDR\_TYPE\_RANDOM</li> <li>BLE\_ADDR\_TYPE\_RPA\_PUB\_DEFAULT</li> <li>BLE\_ADDR\_TYPE\_RPA\_RND\_DEFAULT</li></ul> | +| peer\_addr\_type | Address type of the peer's identity address. Valid values are: <ul><li>BLE\_ADDR\_TYPE\_PUBLIC</li> <li>BLE\_ADDR\_TYPE\_RANDOM</li></ul> This parameter is ignored unless directed advertising is being used. | +| peer\_addr | The peer's six-byte identity address. This parameter is ignored unless directed advertising is being used. | +| duration\_ms | The duration of the advertisement procedure. On expiration, the procedure ends and a BLE\_GAP\_EVENT\_ADV\_COMPLETE event is reported. Units are milliseconds. Specify BLE\_HS\_FOREVER for no expiration. | +| adv\_params | Additional arguments specifying the particulars of the advertising procedure. | +| cb | The callback to associate with this advertising procedure. If advertising ends, the event is reported through this callback. If advertising results in a connection, the connection inherits this callback as its event-reporting mechanism. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop.md new file mode 100644 index 0000000..adb3d87 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop.md @@ -0,0 +1,22 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_adv\_stop</font> + +```c +int +ble_gap_adv_stop(void) +``` + +### Description + +Stops the currently-active advertising procedure. A success return code indicates that advertising has been fully aborted; a new advertising procedure can be initiated immediately. + +### Parameters + +None + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_EALREADY | There is no active advertising procedure. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active.md new file mode 100644 index 0000000..22a7bff --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active.md @@ -0,0 +1,21 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_conn\_active</font> + +```c +int +ble_gap_conn_active(void) +``` + +### Description + +Indicates whether a connect procedure is currently in progress. + +### Parameters + +None + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | No connect procedure in progress. | +| 1 | Connect procedure in progress. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel.md new file mode 100644 index 0000000..4ce05c5 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel.md @@ -0,0 +1,21 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_conn\_cancel</font> + +```c +int +ble_gap_conn_cancel(void) +``` + +### Description + +Aborts a connect procedure in progress. + +### Parameters + +None + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find.md new file mode 100644 index 0000000..e107e9f --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find.md @@ -0,0 +1,24 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_conn\_find</font> + +```c +int +ble_gap_conn_find(uint16_t handle, struct ble_gap_conn_desc *out_desc) +``` + +### Description + +Searches for a connection with the specified handle. If a matching connection is found, the supplied connection descriptor is filled correspondingly. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| handle | The connection handle to search for. | +| out\_desc | On success, this is populated with information relating to the matching connection. Pass NULL if you don't need this information. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_ENOTCONN | No matching connection was found. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_connect.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_connect.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_connect.md new file mode 100644 index 0000000..44b5b40 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_connect.md @@ -0,0 +1,32 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_connect</font> + +```c +int +ble_gap_connect(uint8_t own_addr_type, + uint8_t peer_addr_type, const uint8_t *peer_addr, + const struct ble_gap_conn_params *conn_params, + ble_gap_event_fn *cb, void *cb_arg) +``` + +### Description + +Initiates a connect procedure. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| own\_addr\_type | The type of address the stack should use for itself during connection establishment. <ul><li>BLE\_ADDR\_TYPE\_PUBLIC</li> <li>BLE\_ADDR\_TYPE\_RANDOM</li> <li>BLE\_ADDR\_TYPE\_RPA\_PUB\_DEFAULT</li> <li>BLE\_ADDR\_TYPE\_RPA\_RND\_DEFAULT</li></ul> | +| peer\_addr\_type | The peer's address type. One of: <ul><li>BLE\_HCI\_CONN\_PEER\_ADDR\_PUBLIC</li> <li>BLE\_HCI\_CONN\_PEER\_ADDR\_RANDOM</li> <li>BLE\_HCI\_CONN\_PEER\_ADDR\_PUBLIC\_IDENT</li> <li>BLE\_HCI\_CONN\_PEER\_ADDR\_RANDOM\_IDENT</li> <li>BLE\_GAP\_ADDR\_TYPE\_WL</li></ul> | +| peer\_addr | The identity address of the peer to connect to. This parameter is ignored when the white list is used. | +| duration\_ms | The duration of the discovery procedure. On expiration, the procedure ends and a BLE\_GAP\_EVENT\_DISC\_COMPLETE event is reported. Units are milliseconds. | +| conn\_params | Additional arguments specifying the particulars of the connect procedure. Specify null for default values. | +| cb | The callback to associate with this connect procedure. When the connect procedure completes, the result is reported through this callback. If the connect procedure succeeds, the connection inherits this callback as its event-reporting mechanism. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc.md new file mode 100644 index 0000000..d4cd67a --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc.md @@ -0,0 +1,29 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_disc</font> + +```c +int +ble_gap_disc(uint8_t own_addr_type, int32_t duration_ms, + const struct ble_gap_disc_params *disc_params, + ble_gap_event_fn *cb, void *cb_arg) +``` + +### Description + +Performs the Limited or General Discovery Procedures. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| own\_addr\_type | The type of address the stack should use for itself when sending scan requests. Valid values are: <ul><li>BLE\_ADDR\_TYPE\_PUBLIC</li> <li>BLE\_ADDR\_TYPE\_RANDOM</li> <li>BLE\_ADDR\_TYPE\_RPA\_PUB\_DEFAULT</li> <li>BLE\_ADDR\_TYPE\_RPA\_RND\_DEFAULT</li></ul> This parameter is ignored unless active scanning is being used. | +| duration\_ms | The duration of the discovery procedure. On expiration, the procedure ends and a BLE\_GAP\_EVENT\_DISC\_COMPLETE event is reported. Units are milliseconds. Specify BLE\_HS\_FOREVER for no expiration. | +| disc\_params | Additional arguments specifying the particulars of the discovery procedure. | +| cb | The callback to associate with this discovery procedure. Advertising reports and discovery termination events are reported through this callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active.md new file mode 100644 index 0000000..a094ab9 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active.md @@ -0,0 +1,21 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_disc\_active</font> + +```c +int +ble_gap_disc_active(void) +``` + +### Description + +Indicates whether a discovery procedure is currently in progress. + +### Parameters + +None + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | No discovery procedure in progress. | +| 1 | Discovery procedure in progress. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel.md new file mode 100644 index 0000000..f89b461 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel.md @@ -0,0 +1,22 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_disc\_cancel</font> + +```c +int +ble_gap_disc_cancel(void) +``` + +### Description + +Cancels the discovery procedure currently in progress. A success return code indicates that scanning has been fully aborted; a new discovery or connect procedure can be initiated immediately. + +### Parameters + +None + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_EALREADY | There is no discovery procedure to cancel. | +| other | Other nonzero on unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate.md new file mode 100644 index 0000000..7e23d99 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate.md @@ -0,0 +1,25 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_security\_initiate</font> + +```c +int +ble_gap_security_initiate(uint16_t conn_handle) +``` + +### Description + +Initiates the GAP encryption procedure. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The handle corresponding to the connection to encrypt. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_ENOTCONN | The there is no connection with the specified handle. | +| BLE\_HS\_EALREADY | An encrpytion procedure for this connection is already in progress. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate.md new file mode 100644 index 0000000..4797f74 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate.md @@ -0,0 +1,25 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_terminate</font> + +```c +int +ble_gap_terminate(uint16_t conn_handle, uint8_t hci_reason) +``` + +### Description + +Terminates an established connection. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The handle corresponding to the connection to terminate. | +| hci\_reason | The HCI error code to indicate as the reason for termination. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_ENOTCONN | There is no connection with the specified handle. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params.md new file mode 100644 index 0000000..6f5547d --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_update\_params</font> + +```c +int +ble_gap_update_params(uint16_t conn_handle, + const struct ble_gap_upd_params *params) +``` + +### Description + +Initiates a connection parameter update procedure. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The handle corresponding to the connection to update. | +| params | The connection parameters to attempt to update to. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_ENOTCONN | The there is no connection with the specified handle. | +| BLE\_HS\_EALREADY | A connection update procedure for this connection is already in progress. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set.md b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set.md new file mode 100644 index 0000000..5876cfb --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set.md @@ -0,0 +1,25 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gap\_wl\_set</font> + +```c +int +ble_gap_wl_set(const struct ble_gap_white_entry *white_list, + uint8_t white_list_count) +``` + +### Description + +Overwrites the controller's white list with the specified contents. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| white\_list | The entries to write to the white list. | +| white\_list\_count | The number of entries in the white list. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/ble_gattc.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/ble_gattc.md b/docs/network/ble/ble_hs/ble_gattc/ble_gattc.md new file mode 100644 index 0000000..9ed260c --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/ble_gattc.md @@ -0,0 +1,37 @@ +## <font color="F2853F" style="font-size:24pt">NimBLE Host GATT Client Reference</font> + +### Introduction + +The Generic Attribute Profile (GATT) manages all activities involving services, characteristics, and descriptors. The client half of the GATT API initiates GATT procedures. + +### Header + +```c +#include "host/ble_hs.h" +``` + +### Definitions + +[BLE host GATT client definitions](definitions/ble_gattc_defs.md) + +### Functions + +| Function | Description | +|----------|-------------| +| [ble_gattc_disc_all_chrs](functions/ble_gattc_disc_all_chrs.md) | Initiates GATT procedure: Discover All Characteristics of a Service. | +| [ble_gattc_disc_all_dscs](functions/ble_gattc_disc_all_dscs.md) | Initiates GATT procedure: Discover All Characteristic Descriptors. | +| [ble_gattc_disc_all_svcs](functions/ble_gattc_disc_all_svcs.md) | Initiates GATT procedure: Discover All Primary Services. | +| [ble_gattc_disc_chrs_by_uuid](functions/ble_gattc_disc_chrs_by_uuid.md) | Initiates GATT procedure: Discover Characteristics by UUID. | +| [ble_gattc_disc_svc_by_uuid](functions/ble_gattc_disc_svc_by_uuid.md) | Initiates GATT procedure: Discover Primary Service by Service UUID. | +| [ble_gattc_exchange_mtu](functions/ble_gattc_exchange_mtu.md) | Initiates GATT procedure: Exchange MTU. | +| [ble_gattc_find_inc_svcs](functions/ble_gattc_find_inc_svcs.md) | Initiates GATT procedure: Find Included Services. | +| [ble_gattc_notify](functions/ble_gattc_notify.md) | Sends a characteristic notification. | +| [ble_gattc_notify_custom](functions/ble_gattc_notify_custom.md) | Sends a "free-form" characteristic notification. | +| [ble_gattc_read](functions/ble_gattc_read.md) | Initiates GATT procedure: Read Characteristic Value. | +| [ble_gattc_read_by_uuid](functions/ble_gattc_read_by_uuid.md) | Initiates GATT procedure: Read Using Characteristic UUID. | +| [ble_gattc_read_long](functions/ble_gattc_read_long.md) | Initiates GATT procedure: Read Long Characteristic Values. | +| [ble_gattc_read_mult](functions/ble_gattc_read_mult.md) | Initiates GATT procedure: Read Multiple Characteristic Values. | +| [ble_gattc_write](functions/ble_gattc_write.md) | Initiates GATT procedure: Write Characteristic Value. | +| [ble_gattc_write_long](functions/ble_gattc_write_long.md) | Initiates GATT procedure: Write Long Characteristic Values. | +| [ble_gattc_write_no_rsp](functions/ble_gattc_write_no_rsp.md) | Initiates GATT procedure: Write Without Response. | +| [ble_gattc_write_reliable](functions/ble_gattc_write_reliable.md) | Initiates GATT procedure: Reliable Writes. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/definitions/ble_gattc_defs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/definitions/ble_gattc_defs.md b/docs/network/ble/ble_hs/ble_gattc/definitions/ble_gattc_defs.md new file mode 100644 index 0000000..089761a --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/definitions/ble_gattc_defs.md @@ -0,0 +1,82 @@ +## <font color="#F2853F" style="font-size:24pt">GATT Client Definitions</font> + +```c +struct ble_gatt_error { + uint16_t status; + uint16_t att_handle; +}; +``` + +```c +struct ble_gatt_svc { + uint16_t start_handle; + uint16_t end_handle; + uint8_t uuid128[16]; +}; +``` + +```c +struct ble_gatt_attr { + uint16_t handle; + uint16_t offset; + uint16_t value_len; + const void *value; +}; +``` + +```c +struct ble_gatt_chr { + uint16_t def_handle; + uint16_t val_handle; + uint8_t properties; + uint8_t uuid128[16]; +}; +``` + +```c +struct ble_gatt_dsc { + uint16_t handle; + uint8_t uuid128[16]; +}; +``` + +```c +typedef int ble_gatt_mtu_fn(uint16_t conn_handle, + const struct ble_gatt_error *error, + uint16_t mtu, void *arg); +``` + +```c +typedef int ble_gatt_disc_svc_fn(uint16_t conn_handle, + const struct ble_gatt_error *error, + const struct ble_gatt_svc *service, + void *arg); +``` + +```c +typedef int ble_gatt_attr_fn(uint16_t conn_handle, + const struct ble_gatt_error *error, + const struct ble_gatt_attr *attr, + void *arg); +``` + +```c +typedef int ble_gatt_reliable_attr_fn(uint16_t conn_handle, + const struct ble_gatt_error *error, + const struct ble_gatt_attr *attrs, + uint8_t num_attrs, void *arg); +``` + +```c +typedef int ble_gatt_chr_fn(uint16_t conn_handle, + const struct ble_gatt_error *error, + const struct ble_gatt_chr *chr, void *arg); +``` + +```c +typedef int ble_gatt_dsc_fn(uint16_t conn_handle, + const struct ble_gatt_error *error, + uint16_t chr_def_handle, + const struct ble_gatt_dsc *dsc, + void *arg); +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs.md new file mode 100644 index 0000000..85b1032 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs.md @@ -0,0 +1,29 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_disc\_all\_chrs</font> + +```c +int +ble_gattc_disc_all_chrs(uint16_t conn_handle, uint16_t start_handle, + uint16_t end_handle, ble_gatt_chr_fn *cb, + void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Discover All Characteristics of a Service. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| start\_handle | The handle to begin the search at (generally the service definition handle). | +| end\_handle | The handle to end the search at (generally the last handle in the service). | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs.md new file mode 100644 index 0000000..f3a6380 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs.md @@ -0,0 +1,29 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_disc\_all\_dscs</font> + +```c +int +ble_gattc_disc_all_dscs(uint16_t conn_handle, uint16_t chr_def_handle, + uint16_t chr_end_handle, + ble_gatt_dsc_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Discover All Characteristic Descriptors. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| chr\_def\_handle | The handle of the characteristic definition attribute. | +| chr\_end\_handle | The last handle in the characteristic definition. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs.md new file mode 100644 index 0000000..bf37569 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs.md @@ -0,0 +1,23 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_disc\_all\_svcs</font> + +```c +int +ble_gattc_disc_all_svcs(uint16_t conn_handle, ble_gatt_disc_svc_fn *cb, + void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Discover All Primary Services. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +None http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid.md new file mode 100644 index 0000000..9db26ee --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid.md @@ -0,0 +1,30 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_disc\_chrs\_by\_uuid</font> + +```c +int +ble_gattc_disc_chrs_by_uuid(uint16_t conn_handle, uint16_t start_handle, + uint16_t end_handle, const void *uuid128, + ble_gatt_chr_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Discover Characteristics by UUID. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| start\_handle | The handle to begin the search at (generally the service definition handle). | +| end\_handle | The handle to end the search at (generally the last handle in the service). | +| chr\_uuid128 | The 128-bit UUID of the characteristic to discover. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid.md new file mode 100644 index 0000000..bd3b308 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_disc\_svc\_by\_uuid</font> + +```c +int +ble_gattc_disc_svc_by_uuid(uint16_t conn_handle, const void *svc_uuid128, + ble_gatt_disc_svc_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Discover Primary Service by Service UUID. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| service\_uuid128 | The 128-bit UUID of the service to discover. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu.md new file mode 100644 index 0000000..81de2b4 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu.md @@ -0,0 +1,25 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_exchange\_mtu</font> + +```c +int +ble_gattc_exchange_mtu(uint16_t conn_handle, ble_gatt_mtu_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Exchange MTU. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs.md new file mode 100644 index 0000000..9aaa630 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs.md @@ -0,0 +1,29 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_find\_inc\_svcs</font> + +```c +int +ble_gattc_find_inc_svcs(uint16_t conn_handle, uint16_t start_handle, + uint16_t end_handle, + ble_gatt_disc_svc_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Find Included Services. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| start\_handle | The handle to begin the search at (generally the service definition handle). | +| end\_handle | The handle to end the search at (generally the last handle in the service). | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify.md new file mode 100644 index 0000000..6545cce --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify.md @@ -0,0 +1,24 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_notify</font> + +```c +int +ble_gattc_notify(uint16_t conn_handle, uint16_t chr_val_handle) +``` + +### Description + +Sends a characteristic notification. The content of the message is read from the specified characteristic. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| chr\_val\_handle | The value attribute handle of the characteristic to include in the outgoing notification. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom.md new file mode 100644 index 0000000..c9820e8 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_notify\_custom</font> + +```c +int +ble_gattc_notify_custom(uint16_t conn_handle, uint16_t chr_val_handle, + const void *attr_data, uint16_t attr_data_len) +``` + +### Description + +Sends a "free-form" characteristic notification. The content of the message is specified in the attr parameter. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| chr\_val\_handle | The attribute handle to indicate in the outgoing notification. | +| attr\_data | The characteristic value to include in the outgoing notification. | +| attr\_data\_len | The number of bytes of attribute data to include in the notification. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read.md new file mode 100644 index 0000000..19d49b0 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_read</font> + +```c +int +ble_gattc_read(uint16_t conn_handle, uint16_t attr_handle, + ble_gatt_attr_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Read Characteristic Value. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| attr\_handle | The handle of the characteristic value to read. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid.md new file mode 100644 index 0000000..365ef78 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid.md @@ -0,0 +1,29 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_read\_by\_uuid</font> + +```c +int +ble_gattc_read_by_uuid(uint16_t conn_handle, uint16_t start_handle, + uint16_t end_handle, const void *uuid128, + ble_gatt_attr_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Read Using Characteristic UUID. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| start\_handle | The first handle to search (generally the handle of the service definition). | +| end\_handle | The last handle to search (generally the last handle in the service definition). | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long.md new file mode 100644 index 0000000..89f8d73 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_read\_long</font> + +```c +int +ble_gattc_read_long(uint16_t conn_handle, uint16_t handle, + ble_gatt_attr_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Read Long Characteristic Values. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| handle | The handle of the characteristic value to read. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult.md new file mode 100644 index 0000000..2956d13 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult.md @@ -0,0 +1,29 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_read\_mult</font> + +```c +int +ble_gattc_read_mult(uint16_t conn_handle, const uint16_t *handles, + uint8_t num_handles, ble_gatt_attr_fn *cb, + void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Read Multiple Characteristic Values. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| handles | An array of 16-bit attribute handles to read. | +| num\_handles | The number of entries in the "handles" array. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write.md new file mode 100644 index 0000000..ec074c1 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write.md @@ -0,0 +1,29 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_write</font> + +```c +int +ble_gattc_write(uint16_t conn_handle, uint16_t attr_handle, const void *value, + uint16_t value_len, ble_gatt_attr_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Write Characteristic Value. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| attr\_handle | The handle of the characteristic value to write to. | +| value | The value to write to the characteristic. | +| value\_len | The number of bytes to write. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long.md new file mode 100644 index 0000000..69f1f89 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long.md @@ -0,0 +1,30 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_write\_long</font> + +```c +int +ble_gattc_write_long(uint16_t conn_handle, uint16_t attr_handle, + const void *value, uint16_t value_len, + ble_gatt_attr_fn *cb, void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Write Long Characteristic Values. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| attr\_handle | The handle of the characteristic value to write to. | +| value | The value to write to the characteristic. | +| value\_len | The number of bytes to write. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp.md new file mode 100644 index 0000000..3983b8b --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_write\_no\_rsp</font> + +```c +int +ble_gattc_write_no_rsp(uint16_t conn_handle, uint16_t attr_handle, + const void *value, uint16_t value_len) +``` + +### Description + +Initiates GATT procedure: Write Without Response. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| attr\_handle | The handle of the characteristic value to write to. | +| value | The value to write to the characteristic. | +| value\_len | The number of bytes to write. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| [BLE host core return code](../../ble_hs_return_codes/#return-codes-core) | Unexpected error. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable.md b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable.md new file mode 100644 index 0000000..302eb99 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gattc\_write\_reliable</font> + +```c +int +ble_gattc_write_reliable(uint16_t conn_handle, + const struct ble_gatt_attr *attrs, + int num_attrs, ble_gatt_reliable_attr_fn *cb, + void *cb_arg) +``` + +### Description + +Initiates GATT procedure: Reliable Writes. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| conn\_handle | The connection over which to execute the procedure. | +| attrs | An array of attribute descriptors; specifies which characteristics to write to and what data to write to them. | +| num\_attrs | The number of characteristics to write; equal to the number of elements in the 'attrs' array. | +| cb | The function to call to report procedure status updates; null for no callback. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +None http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gatts/ble_gatts.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gatts/ble_gatts.md b/docs/network/ble/ble_hs/ble_gatts/ble_gatts.md new file mode 100644 index 0000000..33123a9 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gatts/ble_gatts.md @@ -0,0 +1,24 @@ +## <font color="F2853F" style="font-size:24pt">NimBLE Host GATT Client Reference</font> + +### Introduction + +The Generic Attribute Profile (GATT) manages all activities involving services, characteristics, and descriptors. The server half of the GATT API handles registration and responding to GATT clients. + +### Header + +```c +#include "host/ble_hs.h" +``` + +### Definitions + +[BLE host GATT server definitions](definitions/ble_gatts_defs.md) + +### Functions + +| Function | Description | +|----------|-------------| +| [ble_gatts_find_chr](functions/ble_gatts_find_chr.md) | Retrieves the pair of attribute handles associated with a local GATT characteristic. | +| [ble_gatts_find_dsc](functions/ble_gatts_find_dsc.md) | Retrieves the attribute handle associated with a local GATT descriptor. | +| [ble_gatts_find_svc](functions/ble_gatts_find_svc.md) | Retrieves the attribute handle associated with a local GATT service. | +| [ble_gatts_register_svcs](functions/ble_gatts_register_svcs.md) | Registers a set of services, characteristics, and descriptors to be accessed by GATT clients. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gatts/definitions/ble_gatts_defs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gatts/definitions/ble_gatts_defs.md b/docs/network/ble/ble_hs/ble_gatts/definitions/ble_gatts_defs.md new file mode 100644 index 0000000..a87491a --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gatts/definitions/ble_gatts_defs.md @@ -0,0 +1,187 @@ +## <font color="#F2853F" style="font-size:24pt">GATT Client Definitions/font> + +```c +typedef int ble_gatt_access_fn(uint16_t conn_handle, uint16_t attr_handle, + uint8_t op, struct ble_gatt_access_ctxt *ctxt, + void *arg); +``` + +```c +typedef uint16_t ble_gatt_chr_flags; +``` + +```c +struct ble_gatt_chr_def { + /** + * Pointer to first element in a uint8_t[16]; use the BLE_UUID16 macro for + * 16-bit UUIDs; NULL if there are no more characteristics in the service. + */ + const uint8_t *uuid128; + + /** + * Callback that gets executed when this characteristic is read or + * written. + */ + ble_gatt_access_fn *access_cb; + + /** Optional argument for callback. */ + void *arg; + + /** + * Array of this characteristic's descriptors. NULL if no descriptors. + * Do not include CCCD; it gets added automatically if this + * characteristic's notify or indicate flag is set. + */ + struct ble_gatt_dsc_def *descriptors; + + /** Specifies the set of permitted operations for this characteristic. */ + ble_gatt_chr_flags flags; + + /** + * At registration time, this is filled in with the characteristic's value + * attribute handle. + */ + uint16_t * const val_handle; +}; +``` + +```c +struct ble_gatt_svc_def { + /** + * One of the following: + * o BLE_GATT_SVC_TYPE_PRIMARY - primary service + * o BLE_GATT_SVC_TYPE_SECONDARY - secondary service + * o 0 - No more services in this array. + */ + uint8_t type; + + /** + * Pointer to first element in a uint8_t[16]; use the BLE_UUID16 macro for + * 16-bit UUIDs. + */ + const uint8_t *uuid128; + + /** + * Array of pointers to other service definitions. These services are + * reported as "included services" during service discovery. Terminate the + * array with NULL. + */ + const struct ble_gatt_svc_def **includes; + + /** + * Array of characteristic definitions corresponding to characteristics + * belonging to this service. + */ + const struct ble_gatt_chr_def *characteristics; +}; +``` + +```c +struct ble_gatt_access_ctxt { + union { + /** + * The characteristic definition corresponding to the characteristic + * being accessed. This is what the app registered at startup. + */ + const struct ble_gatt_chr_def *chr; + + /** + * The descriptor definition corresponding to the descriptor being + * accessed. This is what the app registered at startup. + */ + const struct ble_gatt_dsc_def *dsc; + }; + + struct ble_att_svr_access_ctxt *att; +}; +``` + +```c +struct ble_gatt_dsc_def { + /** + * The first element in a uint8_t[16]; use the BLE_UUID16 macro for 16-bit + * UUIDs; NULL if there are no more descriptors in the characteristic. + */ + uint8_t *uuid128; + + /** Specifies the set of permitted operations for this descriptor. */ + uint8_t att_flags; + + /** Callback that gets executed when the descriptor is read or written. */ + ble_gatt_access_fn *access_cb; + + /** Optional argument for callback. */ + void *arg; +}; +``` + +```c +/** + * Context passed to the registration callback; represents the GATT service, + * characteristic, or descriptor being registered. + */ +union ble_gatt_register_ctxt { + /** Service; valid if op == BLE_GATT_REGISTER_OP_SVC. */ + struct { + /** The ATT handle of the service definition attribute. */ + uint16_t handle; + + /** + * The service definition representing the service being + * registered. + */ + const struct ble_gatt_svc_def *svc_def; + } svc; + + /** Characteristic; valid if op == BLE_GATT_REGISTER_OP_CHR. */ + struct { + /** The ATT handle of the characteristic definition attribute. */ + uint16_t def_handle; + + /** The ATT handle of the characteristic value attribute. */ + uint16_t val_handle; + + /** + * The characteristic definition representing the characteristic being + * registered. + */ + const struct ble_gatt_chr_def *chr_def; + + /** + * The service definition corresponding to the characteristic's parent + * service. + */ + const struct ble_gatt_svc_def *svc_def; + } chr; + + /** Descriptor; valid if op == BLE_GATT_REGISTER_OP_DSC. */ + struct { + /** The ATT handle of the descriptor definition attribute. */ + uint16_t handle; + + /** + * The descriptor definition corresponding to the descriptor being + * registered. + */ + const struct ble_gatt_dsc_def *dsc_def; + + /** + * The characteristic definition corresponding to the descriptor's + * parent characteristic. + */ + const struct ble_gatt_chr_def *chr_def; + + /** + * The service definition corresponding to the descriptor's grandparent + * service + */ + const struct ble_gatt_svc_def *svc_def; + } dsc; +}; +``` + +```c +typedef void ble_gatt_register_fn(uint8_t op, + union ble_gatt_register_ctxt *ctxt, + void *arg); +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr.md b/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr.md new file mode 100644 index 0000000..27cb728 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gatts\_find\_chr</font> + +```c +int +ble_gatts_find_chr(const void *svc_uuid128, const void *chr_uuid128, + uint16_t *out_def_handle, uint16_t *out_val_handle) +``` + +### Description + +Retrieves the pair of attribute handles associated with a local GATT characteristic. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| svc\_uuid128 | The UUID of the parent service. | +| chr\_uuid128 | The UUID of the characteristic to look up. | +| out\_def\_handle | On success, populated with the handle of the characteristic definition attribute. Pass null if you don't need this value. | +| out\_val\_handle | On success, populated with the handle of the characteristic value attribute. Pass null if you don't need this value. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_ENOENT | The specified service or characteristic could not be found. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc.md b/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc.md new file mode 100644 index 0000000..6a2dcc1 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gatts\_find\_dsc</font> + +```c +int +ble_gatts_find_dsc(const void *svc_uuid128, const void *chr_uuid128, + const void *dsc_uuid128, uint16_t *out_handle) +``` + +### Description + +Retrieves the attribute handle associated with a local GATT descriptor. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| svc\_uuid128 | The UUID of the grandparent service. | +| chr\_uuid128 | The UUID of the parent characteristic. | +| dsc\_uuid128 | The UUID of the descriptor ro look up. | +| out\_handle | On success, populated with the handle of the descripytor attribute. Pass null if you don't need this value. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_ENOENT | The specified service, characteristic, or descriptor could not be found. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc.md b/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc.md new file mode 100644 index 0000000..3df3349 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc.md @@ -0,0 +1,24 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gatts\_find\_svc</font> + +```c +int +ble_gatts_find_svc(const void *uuid128, uint16_t *out_handle) +``` + +### Description + +Retrieves the attribute handle associated with a local GATT service. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| uuid128 | The UUID of the service to look up. | +| out\_handle | On success, populated with the handle of the service attribute. Pass null if you don't need this value. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_ENOENT | The specified service could not be found. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs.md b/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs.md new file mode 100644 index 0000000..593ae80 --- /dev/null +++ b/docs/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_gatts\_register\_svcs</font> + +```c +int +ble_gatts_register_svcs(const struct ble_gatt_svc_def *svcs, + ble_gatt_register_fn *cb, void *cb_arg) +``` + +### Description + +Registers a set of services, characteristics, and descriptors to be accessed by GATT clients. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| svcs | A table of the service definitions to be registered. | +| cb | The function to call for each service, characteristic, and descriptor that gets registered. | +| cb\_arg | The optional argument to pass to the callback function. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_ENOMEM | Registration failed due to resource exhaustion. | +| BLE\_HS\_EINVAL | The service definition table contains an invalid element. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_hs.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_hs.md b/docs/network/ble/ble_hs/ble_hs.md new file mode 100644 index 0000000..efde78a --- /dev/null +++ b/docs/network/ble/ble_hs/ble_hs.md @@ -0,0 +1,22 @@ +# NimBLE Host + +### Introduction + +At a high level, the NimBLE stack is is divided into two components: + +* Host +* Controller + +This document is an API reference for the host component. If you are interested in the general structure of the NimBLE stack and its non-host components, you might want to read the [BLE introduction](../ble_intro.md). + +The host sits directly below the application, and it serves as the interface to the application for all BLE operations. + +### Reference + +* [NimBLE Host Return Codes](ble_hs_return_codes.md) +* [Initialization and Configuration](init/init.md) +* [Generic Access Protocol (GAP)](ble_gap/ble_gap.md) +* [Generic Attribute Profile (GATT) Client](ble_gattc/ble_gattc.md) +* [Generic Attribute Profile (GATT) Server](ble_gatts/ble_gatts.md) +* [Identity](ble_hs_id/ble_hs_id.md) +* [Other](other/other.md) http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_hs_id/ble_hs_id.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_hs_id/ble_hs_id.md b/docs/network/ble/ble_hs/ble_hs_id/ble_hs_id.md new file mode 100644 index 0000000..f34162a --- /dev/null +++ b/docs/network/ble/ble_hs/ble_hs_id/ble_hs_id.md @@ -0,0 +1,42 @@ +## <font color="F2853F" style="font-size:24pt">NimBLE Host GAP Reference</font> + +### Introduction + +The identity API provides facilities for querying and configuring your device's addresses. BLE's addressing scheme is quite involved; the summary that follows is only a brief introduction. + +BLE defines four address types: + +| Type | Description | Identity? | Configured with | +|-------------------------------|-------------------------------------------------------------------------------------------------|-----------|---------------------------------------------| +| Public | Address assigned by manufacturer; the three most significant bytes form the manufacturer's OUI. | Yes | N/A; read from controller at startup. | +| Static random | Randomly generated address. | Yes | *ble_hs_id_set_rnd()* | +| Resolvable private (RPA) | Address randomly generated from an identity address and an identity resolving key (IRK). | No | N/A; generated by controller periodically. | +| Non-resolvable private (NRPA) | Randomly generated address. | No | *ble_hs_id_set_rnd()* | + +#### Identity Addresses + +The third column in the above table indicates the _identity_ property of each address type. An identity address never changes, and a device can be identified by one of its unique identity addresses. + +Non-identity addresses are used by devices supporting BLE privacy. A device using the privacy feature frequently changes its own address to a newly-generated non-identity address. By cycling its address, the device makes it impossible for eavesdroppers to track its location. + +A device can have up to two identity addresses at once: one public and one static random. As indicated in the above table, the public identity address cannot be configured; the static random identity address can be set by calling *ble_hs_id_set_rnd()*. + +The address type is selected on a per-GAP-procedure basis. Each time you initiate a GAP procedure, you indicate which address type the device should use for the duration of the procedure. + +### Header + +```c +#include "host/ble_hs.h" +``` + +### Definitions + +None. + +### Functions + +| Function | Description | +|----------|-------------| +| [ble_hs_id_copy_addr](functions/ble_hs_id_copy_addr.md) | Retrieves one of the device's identity addresses. | +| [ble_hs_id_gen_rnd](functions/ble_hs_id_gen_rnd.md) | Generates a new random address. | +| [ble_hs_id_set_rnd](functions/ble_hs_id_set_rnd.md) | Sets the device's random address. | http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/e0b9d12e/docs/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr.md ---------------------------------------------------------------------- diff --git a/docs/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr.md b/docs/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr.md new file mode 100644 index 0000000..ff6896d --- /dev/null +++ b/docs/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr.md @@ -0,0 +1,28 @@ +## <font color="#F2853F" style="font-size:24pt">ble\_hs\_id\_copy\_addr</font> + +```c +int +ble_hs_id_copy_addr(uint8_t id_addr_type, uint8_t *out_id_addr, + int *out_is_nrpa) +``` + +### Description + +Retrieves one of the device's identity addresses. The device can have two identity addresses: one public and one random. The id\_addr\_type argument specifies which of these two addresses to retrieve. + +### Parameters + +| *Parameter* | *Description* | +|-------------|---------------| +| id\_addr\_type | The type of identity address to retrieve. Valid values are: <ul><li>BLE\_ADDR\_TYPE\_PUBLIC</li> <li>BLE\_ADDR\_TYPE\_RANDOM</li></ul> | +| out\_id\_addr | On success, the requested identity address is copied into this buffer. The buffer must be at least six bytes in size. | +| out\_is\_nrpa | On success, the pointed-to value indicates whether the retrieved address is a non-resolvable private address. | + +### Returned values + +| *Value* | *Condition* | +|---------|-------------| +| 0 | Success. | +| BLE\_HS\_EINVAL | An invalid address type was specified. | +| BLE\_HS\_ENOADDR | The device does not have an identity address of the requested type. | +| other | Other ble host core code on error. |
