Alexa Gadgets Service

The BLE GATT Alexa Gadgets Service is a custom service that manages Alexa Gadgets stream transactions. For details about the stream format, see Alexa Gadgets Bluetooth LE Packet Alexa Gadgets Bluetooth LE Packet Format.

The Alexa Gadgets Service is used in the Bluetooth: Alexa Gadgets Peripheral sample.

Service UUID

The 128-bit vendor-specific service UUID is 0000FE03-0000-1000-8000-00805F9B34FB.

Characteristics

This service has two characteristics.

RX Characteristic (2BEEA05B-1879-4BB4-8A2F-72641F82420B)

Notify

Enable notifications for the RX Characteristic to send events and respond to commands.

TX Characteristic (F04EB177-3005-43A7-AC61-A390DDF83076)

Write or Write Without Response

Commands and directives are received as Write Without Response.

API documentation

Header file: include/bluetooth/services/gadgets.h
Source file: subsys/bluetooth/services/gadgets.c
group bt_gadgets

Alexa Gadgets GATT Service API.

Implements the Alexa Gadgets GATT Service, and handles the data format (streams) that wraps the data payload sent over this Service. See Alexa Gadgets documentation for further information: https://developer.amazon.com/en-US/docs/alexa/alexa-gadgets-toolkit/packet-ble.html

Defines

BT_UUID_GADGETS_VAL

UUID of the Gadgets Service.

BT_UUID_GADGETS_SHORT_VAL

Short version of the Gadgets Service UUID. Used in advertisement packets.

BT_UUID_GADGETS_TX_VAL

UUID of the TX Characteristic.

BT_UUID_GADGETS_RX_VAL

UUID of the RX Characteristic.

BT_UUID_GADGETS
BT_UUID_GADGETS_RX
BT_UUID_GADGETS_TX

Typedefs

typedef bool (*bt_gadgets_stream_cb_t)(struct bt_conn *conn, const uint8_t *const data, uint16_t len, bool more_data)

Callback type for data received. Returns false if type is unsupported.

typedef void (*bt_gadgets_sent_cb_t)(struct bt_conn *conn, const void *buf, bool success)

Callback type for data sent.

typedef void (*bt_gadgets_ccc_update_cb_t)(bool enabled)

Callback type for CCCD updated.

Enums

enum bt_gadget_result

Gadgets Service result codes.

Values:

enumerator BT_GADGETS_RESULT_CODE_SUCCESS

Gadget result code: success.

enumerator BT_GADGETS_RESULT_CODE_UNKNOWN

Gadget result code: unknown error.

enumerator BT_GADGETS_RESULT_CODE_UNSUPPORTED

Gadget result code: unsupported error.

enum bt_gadgets_stream_id

Gadgets Service stream types. See Gadgets documentation for details: https://developer.amazon.com/en-US/docs/alexa/alexa-gadgets-toolkit/packet-ble.html#streams.

Values:

enumerator BT_GADGETS_STREAM_ID_CONTROL

Control stream ID

enumerator BT_GADGETS_STREAM_ID_ALEXA

Alexa stream ID

enumerator BT_GADGETS_STREAM_ID_OTA

OTA stream ID

Functions

int bt_gadgets_init(const struct bt_gadgets_cb *callbacks)

Initialize the service.

This function registers the Gadgets BLE service with two characteristics, TX and RX.

Parameters

  • [in] callbacks: Struct with function pointers to callbacks for service events.

Return Value

  • 0: If initialization is successful. Otherwise, a negative value is returned.

int bt_gadgets_stream_send(struct bt_conn *conn, enum bt_gadgets_stream_id stream, void *data, uint16_t size)

Send data in stream format.

This function encapsulates the data in the stream format and transmits to the peer device.

Parameters

  • [in] conn: Pointer to connection object.

  • [in] stream: Stream type to use.

  • [in] data: Pointer to a data buffer. Buffer must be kept valid until bt_gadgets_sent_cb_t is triggered.

  • [in] size: Size of the data in the buffer in bytes.

Return Value

  • 0: If the data is sent. Otherwise, a negative value is returned.

int bt_gadgets_send(struct bt_conn *conn, void *data, uint16_t size)

Send data without stream formatting.

No encapsulation or fragmentation is done of this data. Data buffer does not need to be kept valid after this function returns.

Parameters

  • [in] conn: Pointer to connection object.

  • [in] data: Pointer to a data buffer.

  • [in] size: Size of the data in the buffer in bytes.

Return Value

  • 0: If the data is sent. Otherwise, a negative value is returned.

uint16_t bt_gadgets_max_send(struct bt_conn *conn)

Get maximum data length that can be used for bt_gadgets_send.

Return

Maximum data length.

Parameters

  • [in] conn: Pointer to connection object.

struct bt_gadgets_cb
#include <gadgets.h>

Pointers to the callback functions for service events.

Public Members

bt_gadgets_stream_cb_t control_stream_cb

Callback for incoming control streams.

bt_gadgets_stream_cb_t alexa_stream_cb

Callback for incoming Alexa streams.

bt_gadgets_sent_cb_t sent_cb

Callback for stream and non-stream data sent.

bt_gadgets_ccc_update_cb_t ccc_cb

Callback for CCC descriptor updated.