GATT Client and Server Functions - v5.0 (2023)

Look at the release documentation:5,0|This version only works with Simplicity Studio 5. If you have Simplicity Studio 4, please switch to2.13. | For more versions seehistory.

introduction

Bluetooth Low Energy is a powerful and complex technology that differs from classic Bluetooth in that it has a predefined set of official profiles to choose from. Although Bluetooth Low Energy is preset (aka "default")profiles specified by Bluetooth SIG, are just the tip of the iceberg, a small subset of the functionality that can be achieved with BLE.

In many (or even most) cases, the best option is to create custom profiles for your application, as this offers maximum flexibility without the cost involved. In fact, it can be even easier than using one of the default profiles, since you can define exactly how everything works, instead of tailoring your app to something that's already defined. Since there is no official generic "serial port profile" in the BLE world like B.SPP in classic Bluetooth, sometimes a custom implementation is the only option to do what you need.

For an effective custom implementation, it's important to understand how a BLE connection works, the role the devices involved play, and how data is transmitted wirelessly from one device to another. Many terms are used, most of which are not interchangeable and mean different things:central, peripheral, client, server, announce, scan, read, write, notify and display. Understanding the terminology makes it easy to describe and create your BLE application.

quick View

This document covers the following:

• ClientDevices access remote resources using the GATT protocol over a BLE connection. Usually (but not necessarily) the parent is the client.
• serverThe devices have a local database and access control methods and make the resources available to the remote client. Usually the peripheral is the server (but not necessarily).
• you can useread, write, notify, oindicateOperations to move data between the client and the server.
  • LermiwriteThe operations are requested by the client and the server responds (or acknowledges).
  • notifymiindicateThe operations are initiated by the client but also by the server and provide a way to transfer data to the client.
  • notificationsare not confirmed whiletipsthey are recognized. So notifications are faster but less reliable.

For information on parent and peripheral roles, seeCentral and peripheral functions.

Servidor GATT vs. Cliente GATT

An important concept in the BLE project is the difference between a GATT server and a GATT client (where GATT stands forGRAMSenergeticFORtax profile). These roles are not mutually exclusive, although your device is usually just a server or a client. The functions performed by your device depend on the intended functionality. This is a basic summary of the features:

• GATT customer- a device that accesses data on the remote GATT server through read, write, notify, or display operations
• Server GATT- a device that stores data locally and provides data access methods to a remote GATT client

unlike mecorresponding user manual, it's easy to see that a device can be both at the same time, depending on how your application defines the data structure and data flow for each side of the connection. Although most commonly the peripheral device is the GATT server and the central device is the GATT client, this is not necessary.The GATT functionality of a device is logically separated from the central/peripheral function. The core/peripheral roles control how the BLE radio link is managed, while the client/server roles are determined by data flow and storage.

Most of the sample projects in the SDK file and implement inline peripherals designed as GATT servers. These can be easily tested with ourEFR Connect App(Available forAndroidmiiOS). However, there are also some examples that implement the central end of the connection designed as GATT clients.

Receive vs send - move data

In BLE projects created with the Bluetooth SDK, the GATT framework can be configured using Simplicity Studio's built-in tool called the Bluetooth GATT Configurator. They can be found in the configuration tools in the .slcp file. After changing the GATT settings, gatt_db.c/.h andgatt.xmlFiles are generated.

The structure and flow of data are always defined on the GATT server. The client uses whatever is exposed by the server.

And use IAR Embedded Workbench, consultProfile Toolkit Developer Guide.

GATT structure

A GATT database implements one or more profiles consisting of one or more services. Each service consists of one or more resources. For example, in schematic form:

• Profile 1
  • Service A
    • feature for
    • characteristic b
    • characteristic c
  • Service B
    • merkmal d
    • Merkmal z
• Profile 2
  • Service C
    • resource f
    • characteristic g
    • characteristic h
  • service d
    • characteristic
    • merkmal j
• Profile 3
  • services
    • characteristic k
    • merkmal l
    • resource m
  • F service
    • feature no.
    • resource or

You can deploy as many profiles, services, and features as you want. They can be fully customized, in which case they would use their own 128-bit UUIDs generated by the GATT configurator. Alternatively, you can create a project that implements the adopted specifications by referencing the online Bluetooth SIG definitions.Profile, services and properties. When doing this, it often makes more sense to start at the profile level and work from there, as the full list of features includes many things that are possibly irrelevant to your design. You can also combine these two, using some legacy and proprietary profiles/services.

Any BLE device acting as a GATT server must implement the officialGeneral Access Service. This includes two mandatory features, viz.Device NamemiLook. These are similar to thisfriendly namemidevice classValues ​​used by classic Bluetooth. This is an example of a minimal absolute GATT definition as shown in the GATT Configurator:

attributes and properties

From time to time, you'll hear or see the terms "attribute" and "trait" used interchangeably, and while this isn't entirely incorrect, it's not entirely accurate and can be confusing. remember that oneServiceconsists of one or moreCharacteristics. However, only onefeature, usually the most specific level for which we define our GATT framework, can consist of many different levelsAttribute.

allAttributeit receives a unique numeric identifier that the GATT client can use to reference, access, and modify. Each property has a parent attribute that provides access to the value stored in the database for that property. When you read about "Write a value to this property" or "Read the value of this property", read/write operations are performed on the parent data attribute.

Other related attributes are read-only, for example BADescription of the resource userattribute, some control the behavior of the trait, such asClient Property ConfigurationAttribute used to enablenotifyoindicateoperations. The BLE stack and SDK tools generate them as needed based on the settings defined in the GATT configurator.

Each attribute has a UUID, which can be 16 bits long (for example, "180a") or 128 bits (for example, "e7add780-b042-4876-aae1-112855353cc1"). All 16-bit UUIDs are defined by the Bluetooth SIG and are known asfictionalUUID. All 128-bit UUIDs are custom and can be used for any purpose without Bluetooth SIG permission. Two very common 16-bit UUIDs that you will see are2901, the attribute User Description of Attributes (defined in the User Description field of the GATT Editor), and2902, the Client Feature Configuration attribute (created by our SDK when "notify" o "indicate" is enabled in a feature).

Note that technically some attribute UUIDs do not have to be unique. HisClawthey are always unique, but the UUIDs occasionally overlap. For example, each client resource configuration attribute has a UUID of0x2902although there could be a dozen of them in a single GATT database. You mustAlways provide fully unique UUIDs to your own custom propertiesBut don't be alarmed if you test your prototype with Bluetooth NCP Commander, run a descriptor discovery operation, and suddenly see multiple instances of the same UUID for certain things. That is normal.

data transfer methods

read, write, notify, miindicateare thefourBasic operations to move data in BLE. The BLE protocol specification allows a maximum data upload of247 bytesfor these operations. However, for read operations, the supported size is249 bytes. BLE is designed for low power consumption and infrequent short burst data transfers. It is possible to send large amounts of data, but it is generally less efficient than classic Bluetooth when it comes to reaching the maximum transfer rate. The following are some general guidelines on the types of data transfer you should use:

• If the client needs to send data to the server, usewrite.
• If the client needs to retrieve data from the server on demand (i.e. polling), usefurther.
• If the server needs to send data to the client without the client requesting it first, usenotifyoindicate. (Customer mustsubscribe toto these updates before any data is transferred).
• The server cannot retrieve data directly from the client. If this is necessary, the server should usenotifyoindicatesend preset request data to the client, and the client can then awriteOperation to return all the data needed by the server.

The above four BLE data transmission processes are described here. The commands you need to send are shown separately from the events that the stack raises. For example, you can find the complete API reference through Simplicity Studio Launcher in the "Documentation" tab.

Ler

The GATT client requests the read operation for a specific attribute provided by the GATT server. The server then responds with the requested value. In the BLE stack, these API methods are typically involved in read operations:

• sl_bt_gatt_read_characteristic_value domain

  • Read the value of a remote attribute with the given identifier. A single sl_bt_evt_gatt_characteristic_value event is generated when the characteristic value matches an ATT PDU. Otherwise, more than one sl_bt_evt_gatt_characteristic_value event will be generated as the firmware automatically uses the GATT "long read" method.This is the most common method used by a GATT client to read individual attribute values.

• sl_bt_gatt_read_characteristic_value_by_uuid domain

  • Reads the property value of a service from a remote GATT database, specifying the UUID of the property and the identifier of the service that contains that property. An sl_bt_evt_gatt_characteristic_value event is generated when the characteristic value matches an ATT PDU. Otherwise, more than one sl_bt_evt_gatt_characteristic_value event will be generated as the firmware automatically uses the GATT "long read" method.

• sl_bt_gatt_read_multiple_characteristic_values domain

  • With this command, the values ​​of several properties can be read from a remote GATT database at the same time. The sl_bt_evt_gatt_characteristic_value events are generated when values ​​are returned from the remote GATT server.

• sl_bt_evt_gatt_server_user_read_request Cair

  • generatedon the GATT serverwhen a client requests to read dataa property whose "Type" value is set to "User".. Usually the stack automatically performs this operation and the characteristic value stored in RAM directly on the module is sent back to the client. However, with the "User" properties, this data storage and retrieval is entirely up to you. The stack tells you when it was requested, and you have to get it (or generate) and then return it (or not) in whatever format you want. This can be useful, for example, to instantly read I/O status, so that instead of keeping a value in memory or constantly polling it to keep it "fresh", it can wait for the request and read the I/O. The state in place when it arrives. (applies ONLY ifvalue type = "user"is defined in the GATT editor for the specified characteristic)

• sl_bt_gatt_server_send_user_read_response domain

  • It is used to return the desired data when a client request for a "user" property generates an sl_bt_evt_gatt_server_user_read_request. This command retrieves a result code and an actual value, if any. (Applies ONLY ifvalue type = "user"is defined in the GATT editor for the specified characteristic)

Write

this process isrequested by GATT customerto a specific attribute provided by the GATT server while providing a new value to write. The server then stores the new value and (optionally) commits the write operation to the client. In the BLE stack, these API methods are typically involved in write operations:

• sl_bt_gatt_write_characteristic_value domain

  • Writes the value of a remote attribute to a GATT server. this presentsacceptedWrite operation, so that the server responds when the value is written successfully. If the specified value does not fit into an ATT PDU, the GATT "Write Long" procedure is used automatically.This is the most common method used by a GATT client to write individual attribute values.

• sl_bt_evt_gatt_procedure_completed Cair

  • This event indicates that the current GATT procedure completed successfully or failed with an error. All GATT commands except sl_bt_gatt_write_characteristic_value_without_response and sl_bt_gatt_send_characteristic_confirmation trigger this event, so the application must wait for this event before issuing another GATT command (except for the two exceptions above). This event is useful for controlling the flow of the program based on whether or not a critical operation has already completed.

• sl_bt_gatt_write_characteristic_value_sin_respuesta domain

  • Writes the value of a remote attribute to a GATT server. This is exactly the same as the previous command, except that it isnot confirmed. No comments at the end. Like the "Notify" operation, this means that it is faster (multiple uncommitted writes can be performed in a single connection interval) but less reliable than committed writes.

• sl_bt_gatt_prepare_characteristic_value_write domain

  • It can be used to add a different value to the write queue of a remote GATT server. This command can be used in cases where very long attributes must be written or a set of values ​​must be written atomically. Maximum245(ATT_MTU - 5) The amount of data that can be sent at one time. The sl_bt_evt_gatt_procedure_completed event occurs when the preparation is complete. In all cases where the amount of data to transfer fits the BGAPI payload, the sl_bt_gatt_write_characteristic_value command is recommended for writing long values ​​because it transparently executes the "prepare_write" and "execute_write" commands.

The following is an example of a queue write flow:

1. sl_bt_gatt_prepare_characteristic_value_write

   (Video) Ellisys Bluetooth Video 5: Generic Attribute Profile (GATT)

2. Waiting forsl_bt_gatt_prepare_characteristic_value_writeRespondedor

3. Waiting forsl_bt_evt_gatt_procedure_completedCair

4. sl_bt_gatt_prepare_characteristic_value_write

5. Waiting forsl_bt_gatt_prepare_characteristic_value_writeRespondedor

6. Waiting forsl_bt_evt_gatt_procedure_completedCair

7. sl_bt_gatt_execute_characteristic_value_write(conexión, 1)

8. Waiting forsl_bt_gatt_execute_characteristic_value_writeRespondedor

9. Waiting forsl_bt_evt_gatt_procedure_completedCair

• sl_bt_gatt_execute_characteristic_value_write domain

  • Executes (flags = 1) or cancels (flags = 0) any pending write operations that have been queuedsl_bt_gatt_prepare_characteristic_value_write. The stack automatically handles sending queued writes in multiple packets when you run this command, using as many connection intervals as necessary. EITHERsl_bt_evt_gatt_procedure_completedThe event occurs when the execution is complete. On the server side, this looks like a quick series of writes and is handled the same way (by acknowledging each one).

• sl_bt_evt_gatt_server_attribute_value Cair

  • activated inServer GATTwhen the client writes a new value to a specific property. This is the event you can use to determine when a property has been updated and then act on it (parse new command data value, set I/O pins based on saved data, close connection, start read of ADC measurements, etc.).

• sl_bt_evt_gatt_server_user_write_request Cair

  • If type="user" is set to a specific property, this event will be raisedsl_bt_evt_gatt_server_attribute_value. The new value written from the client is provided as one of the parameters of this event, but the stack does not automatically save the value itself to RAM. The user must store or process the value and confirm if necessary. The att_opcode parameter describes which GATT procedure was used to change the value.

• sl_bt_gatt_server_send_user_write_response domain

  (Video) Implementing a Bluetooth GATT Server with an Arduino
  • It is used to return a proper commit result code whensl_bt_evt_gatt_server_user_write_requestThe event is generated by a client's write operation on a "user" property. If this manual acknowledgment is needed, call this command in the same code as the event handler for the associatedsl_bt_evt_gatt_server_user_write_requestCase. (Applies ONLY ifvalue type = "user"is defined in the GATT editor for the specified characteristic).

notify

this process isstarted by serverwhen writing a new value to a reportable property. If the client has subscribed to notifications about this property, the new value is passed to the client when it is written. Notifications are not recognized, so you can send more than one notification in a single connection interval, which can be usefulMaximize performance. The server cannot enable notifications; must be activated by the customer to ensure data transfer. In our BLE stack, these API methods are typically involved in notification operations:

• sl_bt_gatt_server_write_attribute_value domain

  • Writes the value of a local attribute to the GATT server. Writing the value of a property from the local GATT database does not trigger notifications or notifications to the remote GATT client if that property has the notification or notification property and the client has notification or notification enabled. Notifications and notifications are sent to the remote GATT client using the sl_bt_gatt_server_send_characteristic_notification command.

• sl_bt_evt_gatt_server_characteristic_status Cair

  • This event indicates that the remote GATT client changed a local client feature configuration descriptor or that an acknowledgment was received from the remote GATT client after successfully receiving the advertisement. The Status_flags parameter indicates if the configuration of the client property has changed or if an acknowledgment (0x02) has been received. Client_config_flags has the new values ​​for the configuration. If the updated configuration flag is equal1, Notifications are turned on. Yes, it is the same2, Ads are enabled. Yes, it is the same0, both are not activated.

• sl_bt_evt_gatt_characteristic_value Cair

  • This event indicates that a property value has been received from the remote GATT server. The event is triggered as a result of various commands, e.g. b.sl_bt_gatt_read_characteristic_valuemisl_bt_gatt_read_multiple_characteristic_valuesand when the remote GATT server sends alerts or notifications after enabling notifications withsl_bt_gatt_set_characteristic_notification. The att_opcode parameter specifies what type of GATT transaction triggered this event. In particular, if the att_opcode type is sl_bt_gatt_handle_value_indication (0x1d), the application must acknowledge the indication withsl_bt_gatt_send_characteristic_confirmation.This event lets the client know that it has received an updated value.The data sent is provided as part of the event parameters.

Indicate

AindicateThe operation is identical to anotifyoperation, except thatAlerts are acknowledged, but notifications are not.. This increases reliability at the expense of speed. In our BLE stack, these API methods are normally involvedindicateThe operation:

• sl_bt_gatt_server_write_attribute_value domain

  • Writes the value of a local attribute to the GATT server. Writing a property's value to the local GATT database does not trigger notifications or announcements for the remote GATT client if the property has the "Notify" or "Notification" property and the client has notification or announcement enabled. Notifications and notifications are sent to the remote GATT client.sl_bt_gatt_server_send_characteristic_notificationDomain. remember ifTips are recognized, so you can only do this once in a given connection interval. will be accompanied bysl_bt_evt_gatt_server_characteristic_statusEvent with status_flags = 0x2 when the GATT client acknowledgment returns.

• sl_bt_evt_gatt_server_characteristic_status Cair

  • This event indicates that the remote GATT client changed a local client feature configuration descriptor or that an acknowledgment was received from the remote GATT client after successfully receiving the advertisement. The Status_flags parameter indicates if the configuration of the client property has changed or if an acknowledgment (0x02) has been received. Client_config_flags has the new values ​​for the configuration. If the updated configuration flag is equal1, Notifications are turned on. Yes, it is the same2, ads are enabled. Yes, it is the same0**, both are not enabled.

• sl_bt_evt_gatt_characteristic_value Cair

  • This event indicates that a property value has been received from the remote GATT server. This event is generated as a result of various commands, for example B.sl_bt_gatt_read_characteristic_value; and when the remote GATT server sends alerts or notifications after enabling notifications withgatt_set_characteristic_notification. The att_opcode parameter specifies what type of GATT transaction triggered this event. In particular, if the att_opcode type is handle_value_indication (0x1d), the application must confirm the indication withsl_bt_gatt_send_characteristic_confirmation.This event lets the client know that it has received an updated value.. The data sent is provided as part of the event parameters.

• sl_bt_gatt_send_characteristic_confirmation domain

  • Sends a display acknowledgment from the GATT client back to the remote GATT server after a displayed value reaches the client. EITHERsl_bt_evt_gatt_characteristic_valueloads the att_opcode with handle_value_indication (0x1d), which reveals that an indication has been received and should be acknowledged with this command. Confirmation must be sent within 30 seconds, otherwise GATT transactions between client and server will be cancelled. Sometimes there are specific flow control triggers that you need to be very careful about. It can be valuable to keep track of exactly when the commit occurs and what happens before and after.

• sl_bt_evt_gatt_server_characteristic_status Cair

  • This event indicates that the remote GATT client changed a local client feature configuration descriptor or that an acknowledgment was received from the remote GATT client after successfully receiving the advertisement. This event is often ignored, but as mentioned in the previous point, knowing exactly when it occurs is sometimes valuable in order to control the flow of data.

Typically, GATT server functionality is provided by one device and client functionality by another device, but both devices can also provide both types of functionality. For a well-designed, efficient BLE project, this is generally not advantageous. Rather, it often unnecessarily complicates implementation and is therefore not covered here.