diff --git a/config.json b/config.json index cbe7dad..6bc4c6d 100644 --- a/config.json +++ b/config.json @@ -296,6 +296,10 @@ { "match": "sld597-bluetooth-low-power-optimization/use-case-9-i-want-to-exchange-data-with-many-low-power-peripheral-devices.md", "title": "Use Case 9 I Want To Exchange Data With Many Low Power Peripheral Devices" + }, + { + "match": "sld597-bluetooth-low-power-optimization/use-case-10-i-want-to-use-32-peripherals-with-1-central.md", + "title": "Use Case 10 I Want To Use 32 Peripherals With 1 Central" } ] } @@ -410,18 +414,6 @@ { "match": "sld713-gatt-configurator-users-guide-ble-btmesh/index.md", "title": "Introduction" - }, - { - "match": "sld713-gatt-configurator-users-guide-ble-btmesh/01-gatt-configurator-overview.md", - "title": "GATT Configurator Overview" - }, - { - "match": "sld713-gatt-configurator-users-guide-ble-btmesh/02-use-cases.md", - "title": "Use Cases" - }, - { - "match": "sld713-gatt-configurator-users-guide-ble-btmesh/03-dynamic-gatt-configuration.md", - "title": "Dynamic GATT Configuration" } ] }, diff --git a/sld597-bluetooth-low-power-optimization/use-case-10-i-want-to-use-32-peripherals-with-1-central.md b/sld597-bluetooth-low-power-optimization/use-case-10-i-want-to-use-32-peripherals-with-1-central.md new file mode 100644 index 0000000..9be82d9 --- /dev/null +++ b/sld597-bluetooth-low-power-optimization/use-case-10-i-want-to-use-32-peripherals-with-1-central.md @@ -0,0 +1,134 @@ +# Use Case #10: I want to exchange data with up to 32 peripheral devices + +This use case describes an EFR32 central that scales to 32 simultaneous EFR32 peripheral links. It provides a characterization baseline for a Bluetooth Low Energy central that scans for peripherals advertising a known custom service, opens links as peers are found, discovers the required GATT objects, enables notifications, and maintains up to 32 simultaneous connections with selectable PHY operation. For information about the general requirements for handling multiple connections, see [Multi-Peripheral Topology](https://docs.silabs.com/bluetooth/latest/bluetooth-fundamentals-connections/multi-peripheral-topology). + +The reference topology consists of one central and up to 32 peripheral connections. The software baseline is SiSDK 2025.12.3. The hardware baseline is an EFR32MG26 on a BRD4116A radio board with a BRD4002A mainboard. + +**Bluetooth features used**: connections, legacy passive scanning, GATT service discovery, notifications, optional write-without-response traffic, and selectable 1M, 2M, or Coded PHY operation. + +## System Model and Assumptions + +### Topology + +- One EFR32 central maintains N simultaneous connections, where N can scale up to 32. +- The central uses a fixed-size peer table sized for the target connection count and treats each discovered peripheral as a managed slot in that table. +- All links are intended to remain active once opened. Application does not deliberately disconnect. +- Baseline runtime behavior is continuous multi-link management, GATT service discovery, notification reception from peripherals, and automatic reconnect handling after disconnects. +- Scanning restarts after connection events and during maintenance so discovery and reconnection can continue while other connections are active. + +### Baseline Connection Configurations + +- ATT MTU = 247. +- 1M PHY on all links. +- Peripheral latency = 0. +- Connection interval = 50 ms. +- No Bluetooth security used. +- Supervision timeout = 6000 ms. +- DLE enabled, preferred data length = 251. +- Even Connection Scheduling Algorithm enabled. +- Use legacy passive scanning to discover peripherals that advertise the custom 128-bit service UUID in the advertising payload. +- The central expects the peripheral GATT database to expose one custom service containing a notify characteristic for peripheral-to-central data and a write-without-response characteristic for optional central-to-peripheral traffic. +- For the additional application features used, see [Appendix A. Application features](#appendix-a-application-features). + + +### General Configuration Tips + +- Choose the right PHY profile: 1M, 2M, or Coded, based on throughput, airtime, and range requirements. More information on the trade-offs between PHYs can be found [here](https://docs.silabs.com/bluetooth/latest/bluetooth-fundamentals-connections/coded-phy). +- Size the connection budget for 8, 16, 20, 24, or 32 maintained links and set connection parameters and stack memory accordingly. +- Tune minimum and maximum connection event length to control scheduler margin. +- Align data length, ATT MTU, and available buffering with the intended traffic profile. Generic throughput optimization techniques are available [here](https://docs.silabs.com/bluetooth/latest/bluetooth-fundamentals-connections/multi-peripheral-topology). +- An appropriate Bluetooth security mechanism may be implemented using [Security Manager](https://docs.silabs.com/bluetooth/latest/bluetooth-stack-api/sl-bt-sm). +- For cases where 2.4 GHz congestion is expected, such as with coexistence, the following mitigations can be helpful: + - Use longer connection intervals. + - Reduce payload size. + - Use [AFH](https://docs.silabs.com/bluetooth/latest/bluetooth-fundamentals-system-performance/afh). + - Use [Channel Classification](https://docs.silabs.com/bluetooth/latest/bluetooth-fundamentals-system-performance/le-channel-classification). + - Switch to a more robust PHY. + +### Test Conditions + +- Use peripherals that expose the required custom service and characteristic contract expected by the central. +- The test passes if all target links stay connected for the full test duration with no unexpected disconnects. +- Use good RF conditions, low external interference, fixed node placement, and identical peripheral firmware/configuration. + +## Memory Footprint + +### Component-wise Static Memory Breakdown + +| Component / Section | Static RAM (B) | Flash (B) | +| --- | ---: | ---: | +| NVM | 0 | 40,960 | +| Platform drivers / HAL / emlib | 4,059 | 18,897 | +| Stack | 2,752 | 0 | +| Bluetooth stack - controller / link layer | 2,151 | 45,203 | +| RAIL / radio support | 1,660 | 51,748 | +| Application | 1,615 | 2,468 | +| Bluetooth stack - host / common | 746 | 53,476 | +| Toolchain / C runtime | 37 | 1,342 | +| Embedded Security | 225 | 18,046 | +| Platform services | 220 | 9,469 | +| Miscellaneous + linker/alignment overhead | 39 | 119 | +| **Total static RAM excluding heap** | **13,504** | | +| Reserved heap | 248,640 | 0 | +| **Total Flash** | | **241,728** | + +> Note: The memory consumption reported under Application in the preceding table includes the features listed in [Appendix A. Application features](#appendix-a-application-features) and may vary depending on the application. Component grouping follows [Appendix B](#appendix-b-object-file-grouping-used-for-the-memory-breakdown). + +## Failure Modes and Mitigations + +| Failure Mode | Typical Trigger | What to Watch | Likely Outcome | First Mitigation | +| --- | --- | --- | --- | --- | +| Event overlap | Short intervals, long events, many active links | Link bring-up stability, scheduler margin | Delayed service | Increase interval or reduce CE length | +| Missed events | High load, RF retries, or aggressive traffic settings | Disconnect count, supervision margin | Link instability | Lower duty cycle or payload size | +| Rising retransmissions | RF congestion or weak links | Retry rate, throughput drop | Reduced throughput | Improve RF conditions or use longer intervals | +| Timeout risk | Repeated missed service windows | Disconnect reasons, supervision timeout | Disconnects | Increase interval margin and reduce link load | +| Reconnect churn | Intermittent peripherals or marginal RF conditions | Reconnect attempts and dwell-time drops | Link flapping | Implement reconnection backoff | + +## Decision Tree: When to Choose PAwR Instead of Many Connections + +Use this quick check: + +| If your design needs... | Prefer... | +| --- | --- | +| Per-node connection state, GATT discovery, notifications, writes, or low-latency two-way exchange for each device | Many connections | +| Mostly synchronized broadcast data, with optional scheduled responses from many devices | PAwR | +| More devices than the connection scheduler can comfortably maintain, or reconnect churn is the main bottleneck | PAwR, if the application can avoid always-on per-node links | + +If both rows apply, start with many connections for up to 32 managed links and evaluate PAwR only if scheduler margin, reconnection behavior, or scaling becomes the limiting factor. + +## Appendix A. Application features + +- Fixed 32-slot peer table with connection statistics and per-peer state machine. +- 2M and Coded PHY are compile time configurable. +- Advertisement filtering for the expected custom 128-bit control service UUID. +- Automatic scan resume after connection and discovery events to fill or restore the 32-link set. +- Standard GATT flow: service, characteristic discovery, notification enablement. +- Compile-time configurable link parameters for PHY, interval, supervision timeout, MTU, and data length. +- Disconnect handling with bounded reconnect backoff and per-peer retry state. +- Optional logging of KPIs (disabled by default): opens, failures, disconnects, discovery failures, throughput, scheduler skips, reconnect attempts, full-32-link dwell time, and heap high-water reporting. +- Central can optionally enable a round-robin mechanism to perform write-without-response across all the connected peripherals. It is disabled in baseline. +- Service UUID: `efcdab89-6745-2301-fedc-ba9876543210`. +- TX notify UUID: `efcdab89-6745-2301-fedc-ba9876543211`. +- RX write UUID: `efcdab89-6745-2301-fedc-ba9876543212`. + + +## Appendix B. Object File Grouping Used for the Memory Breakdown + +The map-file analysis groups the object files into 12 categories. + +| Category | Summary | +| --- | --- | +| Reserved heap | Linker-generated heap reservation used by the memory manager | +| NVM | NVM3 storage reservation and related non-volatile memory support | +| Platform drivers / HAL / emlib | Device startup, low-level drivers, HAL, emlib, GPIO, system support, and NVM3 platform code | +| Stack | Linker-reserved stack region | +| Bluetooth stack - controller / link layer | Link layer scheduler, connection management, advertising, scanning, LL control procedures, packet handling, and controller support | +| RAIL / radio support | RAIL libraries, RF HAL, PHY support, PA support, calibration, timing, and radio sequencer support | +| Application | Application logic, main entry points, generated Bluetooth init, and board/event handlers | +| Bluetooth stack - host / common | GAP, GATT, ATT, L2CAP, BGAPI, bonding, scanner, and common host-side Bluetooth runtime | +| Toolchain / C runtime | C runtime startup, libc/newlib support, math support, and compiler runtime helpers | +| Embedded Security | PSA crypto, SE manager, radio AES support, key handling, storage, and crypto driver integration | +| Platform services | Clock manager, power manager, sleep timer, memory manager, MPU, interrupt manager, and device init support | +| Miscellaneous + linker/alignment overhead | Small uncategorized objects and linker/alignment overhead | + +This grouping is used only to make the memory breakdown easier to read. Some categories contain many object files, while others contain only a few reserved sections or support objects. diff --git a/sld713-gatt-configurator-users-guide-ble-btmesh/01-gatt-configurator-overview.md b/sld713-gatt-configurator-users-guide-ble-btmesh/01-gatt-configurator-overview.md deleted file mode 100644 index 924fcfd..0000000 --- a/sld713-gatt-configurator-users-guide-ble-btmesh/01-gatt-configurator-overview.md +++ /dev/null @@ -1,69 +0,0 @@ -# GATT Configurator Overview - -The GATT Configurator is a simple-to-use tool to help you build your own GATT database. A list of project Profiles/Services/Characteristics/Descriptors is shown on the left and details about the selected item is shown on the right. - -The GATT Configurator is composed of a Custom GATT editor on the left, showing a list of project Profiles/Services/Characteristics/Descriptors, and a Settings editor on the right. A SIG selector allows you to add standard elements to the profile. - -An options menu is provided at the top of the Custom GATT editor. - -The Custom GATT editor is always visible, and the Settings editor opens by default. - -![GATT Configurator with Settings Editor](resources/sld713-image1.png) - -The GATT Configurator menu is: - -![screenshot](resources/sld713-image2.png) - -From left the right, the buttons are for the following: - -1. Add an item. - -2. Duplicate the selected item. - -3. Move the selected item up. - -4. Move the selected item down. - -5. Import a GATT database. - -6. Add Predefined (opens the SIG editor). - -7. Delete the selected item. - -Click Add Predefined to open the SIG selector. - -![GATT Configurator with SIG Selector](resources/sld713-image3.png) - -## SIG Selector - -The SIG Selector displays a list of predefined Profiles, Services, Characteristics, and Descriptors. These items can be filtered, using the filter pane. Tabs allow you to switch between different lists. As shown in the following figure, the pane on the right side of the list displays textual information about the latest selection. To add an item to the Custom GATT editor, mouse over it and click + on the right. The item can then be edited in the Settings Section. The selected SIG service/characteristic/descriptor will be added under the highlighted profile/service/characteristic. Click **\< BACK** to return to the Setting Editor. - -![SIG Selector](resources/sld713-image4.png) - -## Custom GATT Editor - -The Custom GATT Editor displays the items present in the current configuration file. This includes a Custom GATT Profile, Services, Characteristics, and Descriptors displayed as a hierarchical list. The order of items shown reflects the order in which they exist in the GATT database. When the Settings Editor is open, select an item to see its properties and configuration. - -![GATT Custom GATT Editor with Characteristic Selected](resources/sld713-image5.png) - -The \* next to the configuration file name indicates unsaved changes in the configuration. - ->**Note**: The Generic Attribute Service is not listed in the Custom GATT database structure (on the left in the previous figure). This is a special service that is maintained by the stack, and can be added by enabling the **Generic Attribute Service** slider in the settings of the Custom BLE GATT profile. Once enabled, the service will be part of the database. It still will not appear in the Custom GATT database structure, nor on iOS devices as iOS hides this service, but you may see it on Android devices, for example. - -![Generic Attribute Service Enabled](resources/sld713-image6.png) - -### Contributed Items - -Some services are listed in the configurator as “contributed items”. This means that their content is defined in other components, and they cannot be edited from this view. - -## Settings Section - -The Settings editor allows you to configure the properties of items such as Profiles, Services, Characteristics and Descriptors that are present in the Custom GATT editor. Selecting an item populates the relevant configuration options such as the name, ID, properties and capabilities. Any changes made in this section reflect immediately for the selected item. You can minimize the Custom GATT editor while editing if you want. All Characteristics for a Service are included in the same Settings editor pane. - -![Settings Editor](resources/sld713-image7.png) - -## Generating the GATT Database - -Database generation happens automatically when the configuration is saved. The generated source files can be found in the directory named “autogen”. - -![Generated Files](resources/sld713-image8.png) diff --git a/sld713-gatt-configurator-users-guide-ble-btmesh/02-use-cases.md b/sld713-gatt-configurator-users-guide-ble-btmesh/02-use-cases.md deleted file mode 100644 index 2a2cc77..0000000 --- a/sld713-gatt-configurator-users-guide-ble-btmesh/02-use-cases.md +++ /dev/null @@ -1,91 +0,0 @@ -# Use Cases - -This chapter describes common tasks performed with the GATT Configurator. - -## Drag and Drop - -To include predefined items from the source list in your application, drag and drop the item from the Source Section to the Custom GATT section. When you drag and drop a profile or a service, all the Characteristics and Descriptors in the levels underneath get included automatically. Maintaining the hierarchical structure, Descriptors can only be included under Characteristics, which go under Services. - -![Drag and Drop a Service to Include all the Items](resources/sld713-image9.png) - -Within the Custom GATT section, drag and drop can be used to reorder items. This saves the trouble of including and configuring the item again. Similarly, an item can be duplicated and moved around in the section. - -## Create New Item - -Use the Add an item (1) menu option to add a new item in the Custom GATT editor. If the profile is selected, a new Service will be created. If a Service is selected, a new Characteristics is created under the selected item. Descriptors can only be created when you have selected a Characteristic. - -When a new item is selected, the Settings section displays the default properties of the item. Here the item can be configured as per the requirements. - -![Default Values for a Newly Created Characteristic](resources/sld713-image10.png) - -The application gets local access to the GATT database using the characteristic ID. You can enter this by selecting the checkbox and entering a unique ID. - -![Characteristic ID Enabled](resources/sld713-image11.png) - -Upon generation, this ID gets a macro in the `gatt_db.h` file as shown below. - -```C -extern const struct bg_gattdb_def bg_gattdb_data; -#define gattdb_service_changed_char 3 -#define gattdb_device_name 7 -#define gattdb_ota_control 21 -#define gattdb_custom_characteristic 24 -``` - -UUID or Universally Unique identifier are numbers used to identify Services, Characteristics, and Descriptors uniquely. There are two types of UUID: - -1. **16 bit**: These 16-bit UUIDs are predefined by the Bluetooth SIG. Being short they are energy and memory efficient. For example, the Blood Pressure Service has a UUID of 0x1810 whereas the Battery level Characteristic has a UUID of 0x2A19. - -2. **128 bit**: This overcomes the limitation of running out of 16-bit UUIDs and gives the power to declare your own UUIDs for Custom Services and Characteristics. These randomly generated UUIDs in the GATT Configurator are of version 4 (random) variant 1. You can use any UUID for a custom Service or Characteristic if it does not overlap with Bluetooth base UUID: xxxxxxxx-0000-1000-8000-00805F9B34FB. - -While there is no central authority ensuring other devices don’t use the same UUID, there is very little chance (1 in 340 undecillion) that two devices end up with the same UUID. - -## Adding Permissions - -Permissions define what actions can be performed for a given Characteristic or Descriptor. For example, in the Blood Pressure Profile, the Blood Pressure Feature has a Mandatory Read property. For more information about access types and security requirements see the Properties section of [Blue Gecko Bluetooth Profile Toolkit Developer's Guide](https://docs.silabs.com/bluetooth/latest/bluetooth-profile-toolkit-developers-guide/). - -First the required access types can be enabled with the sliders, and then the security requirements can be selected with the checkboxes. - -![Setting Permission for a Characteristic or Descriptor](resources/sld713-image12.png) - ->**Note**: The *notify* and *indicate* attribute is stored in the SIG defined Client Characteristic Configuration Descriptor (a descriptor with the UUID 0x2902, which will be autogenerated when notifications are enabled). If you manually add a CCCD to the characteristic, the descriptor’s value will overwrite this setting. A warning will be displayed on the UI for this case. - -## Adding Capabilities - -Bluetooth SDK 2.4 introduced a new feature called Polymorphic GATT that can be used to dynamically show or hide GATT Services and Characteristics. The GATT Configurator implements this feature using GATT capabilities. This section describes how to do it. - -To summarize how capabilities work, each Service/Characteristic can declare several capabilities and the state of the capabilities (enable/disable) determines the visibility of those Services/Characteristics as a bit-wise OR operation. For example, the Service/Characteristic is visible when at least one of its capabilities is enabled and it is not visible when all its capabilities are disabled. - -Always start by declaring the GATT-level capabilities and defining their default value. Select the Custom BLE GATT profile, and click the **+** control in the **Capability declarations** table. After adding a capability, you can change the name and default value. For example, Appearance, Temperature_Measure and Tx_power are added to the profile as shown in the following figure. - -![Declaring GATT-level Capabilities](resources/sld713-image6.png) - -Once those capabilities are added, they become available on each of the services and characteristics. They can be declared from the dropdown list in the **Characteristic capabilities** section. - -On the Service and Characteristic level declared capabilities count as enabled, and the ones which were not selected are disabled. - -![Including GATT-level Capabilities in a Characteristic](resources/sld713-image13.png) - ->**Note**: The capabilities state should not be changed during a connection, as that can cause misbehavior. The safest way is to change the capabilities when no devices are connected. - -## Including Services - -In a Service definition, you can add one or more references to other services, using the Service includes feature. Include definitions consist of a single attribute (the include declaration) that contains all the details required for the client to reference the included service. - -Included services can help avoid duplicating data in a GATT server. If a service will be referenced by other services, you can use this mechanism to save memory and simplify the layout of the GATT server. - -Start by declaring an ID for each service that needs to be included. Services without an ID cannot be referenced. This is done by selecting the ID checkbox and providing an identifier text for the Service. Next, select the Service to be referenced from the dropdown list, named “Service includes”. - -![Referencing a Service using Service Includes](resources/sld713-image14.png) - -## Import and Export a GATT Database - -### Import - -The Import control in the Custom GATT toolbar allows you to import an existing GATT database, using a .btconf file. Note that this will overwrite the existing GATT data. - -![Importing a GATT database](resources/sld713-image15.png) - -### Export - -There is no separate export function. Another project can directly import the GATT database of this project (named gatt_configuration.btconf) diff --git a/sld713-gatt-configurator-users-guide-ble-btmesh/03-dynamic-gatt-configuration.md b/sld713-gatt-configurator-users-guide-ble-btmesh/03-dynamic-gatt-configuration.md deleted file mode 100644 index d1d6637..0000000 --- a/sld713-gatt-configurator-users-guide-ble-btmesh/03-dynamic-gatt-configuration.md +++ /dev/null @@ -1,37 +0,0 @@ -# Dynamic GATT Configuration - -## Overview - -Silicon Labs Bluetooth SDK v3.2 introduced the ability to create the GATT database dynamically with Bluetooth APIs. These dynamically-created GATT attributes can coexist with a static database generated from a GATT XML file. In this case, the attribute table of the static database is placed at the beginning of the database. When new services and characteristics are created dynamically, they are added into the attribute table after the attributes of the static database. - -This feature is recommended for NCP projects. With this method, the target application where the GATT database is located does not need to be modified. Therefore, the database can be built from the host side with the APIs. In other cases, the GATT Configurator is the preferred solution. - -## Usage - -The “Dynamic GATT Database” feature is not included in projects by default. It needs to be installed from the Software Components tab. - -![ the Dynamic GATT Database](resources/sld713-image16.png) - -Operations on the GATT database are done in a “session”. The changes are saved when a session is finished by “committing” the changes. Unsaved changes are invisible to a connected remote GATT client. The modifications only takes effect when the session is finished. - -Each added service and characteristic needs to be started with the appropriate API, or they will not be visible to the connected clients. This start and stop mechanism can be used to have a polymorphic GATT database, as the capability feature is not supported in the dynamic GATT databases. - -The following code snippet shows how to add the Health Thermometer Service and the Temperature Measurement characteristic dynamically to the database. See the Bluetooth API reference manual section "GATT Database" for more details. - -```C -//create a session for the database update - sl_bt_gattdb_new_session(&session); - //add the Thermometer service (UUID: 0x1809) to the database, as an advertised primary service - sl_bt_gattdb_add_service(session, sl_bt_gattdb_primary_service, - SL_BT_GATTDB_ADVERTISED_SERVICE,2,uuid_service, &service); - //add the Temperature measurement (UUID:0x2A1C) characteristic to the service - sl_bt_gattdb_add_uuid16_characteristic(session, service, SL_BT_GATTDB_CHARACTERISTIC_INDICATE, - 0, 0, uuid_characteristic, sl_bt_gattdb_fixed_length_value, - 1, 1, 0, &characteristic); - //activate the new service - sl_bt_gattdb_start_service(session, service); - //activate the new characteristic - sl_bt_gattdb_start_characteristic(session, characteristic); - //save changes and close the database editing session -sl_bt_gattdb_commit(session); -``` diff --git a/sld713-gatt-configurator-users-guide-ble-btmesh/index.md b/sld713-gatt-configurator-users-guide-ble-btmesh/index.md index 95e14ca..b6fc35c 100644 --- a/sld713-gatt-configurator-users-guide-ble-btmesh/index.md +++ b/sld713-gatt-configurator-users-guide-ble-btmesh/index.md @@ -3,3 +3,7 @@ > **Note: This section replaces *UG438: GATT Configurator User’s Guide for Bluetooth LE and Bluetooth Mesh*. Further updates to this user guide will be provided here**. This guide provides the information needed to effectively use the Bluetooth GATT Configurator provided as a part of Simplicity Studio® 5 with Bluetooth SDK 3.x and Bluetooth Mesh SDK 2.x. The GATT Configurator is an intuitive interface providing access to all the Profiles, Services, Characteristics, and Descriptors as defined in the Bluetooth specification. It also supports creating, importing, or exporting custom GATT profiles for Bluetooth applications. This guide reviews the user interface and covers some of the most common uses of the Configurator, and the usage of the Dynamic GATT Configurator. + +## Additional Information + +For more information on specific use cases in the GATT Configurator, see [Bluetooth GATT Configurator](https://docs.silabs.com/ssv6ug/latest/studio-bluetooth-gatt-configurator/).