@@ -33,3 +33,137 @@ advertising packets.
3333```
3434
3535Note: Scan response should be configure before ` InitServer ` .
36+
37+ ## Nimble: additional custom GATT services
38+
39+ The ` ConfigureExtraServices ` API is used to configure additional services
40+ alongside the Matter services. This API allows users to add their own custom
41+ services for provisioning or other purposes.
42+
43+ ### Usage
44+
45+ ```
46+ /* Service access callback */
47+ static int gatt_svc_access(uint16_t conn_handle, uint16_t attr_handle,
48+ struct ble_gatt_access_ctxt *ctxt, void *arg);
49+
50+ /* Service UUID */
51+ static const ble_uuid128_t gatt_svr_svc_uuid =
52+ BLE_UUID128_INIT(0x2d, 0x71, 0xa2, 0x59, 0xb4, 0x58, 0xc8, 0x12,
53+ 0x99, 0x99, 0x43, 0x95, 0x12, 0x2f, 0x46, 0x59);
54+
55+ /* A characteristic that can be subscribed to */
56+ static uint16_t gatt_svr_chr_val_handle;
57+ static const ble_uuid128_t gatt_svr_chr_uuid =
58+ BLE_UUID128_INIT(0x00, 0x00, 0x00, 0x00, 0x11, 0x11, 0x11, 0x11,
59+ 0x22, 0x22, 0x22, 0x22, 0x33, 0x33, 0x33, 0x33);
60+
61+ /* A custom descriptor */
62+ static const ble_uuid128_t gatt_svr_dsc_uuid =
63+ BLE_UUID128_INIT(0x01, 0x01, 0x01, 0x01, 0x12, 0x12, 0x12, 0x12,
64+ 0x23, 0x23, 0x23, 0x23, 0x34, 0x34, 0x34, 0x34);
65+
66+ {
67+ std::vector<struct ble_gatt_svc_def> gatt_svr_svcs = {
68+ {
69+ /*** Service ***/
70+ .type = BLE_GATT_SVC_TYPE_PRIMARY,
71+ .uuid = &gatt_svr_svc_uuid.u,
72+ .characteristics = (struct ble_gatt_chr_def[])
73+ { {
74+ /*** This characteristic can be subscribed to by writing 0x00 and 0x01 to the CCCD ***/
75+ .uuid = &gatt_svr_chr_uuid.u,
76+ .access_cb = gatt_svc_access,
77+ .flags = BLE_GATT_CHR_F_READ | BLE_GATT_CHR_F_WRITE | BLE_GATT_CHR_F_NOTIFY | BLE_GATT_CHR_F_INDICATE,
78+ .val_handle = &gatt_svr_chr_val_handle,
79+ .descriptors = (struct ble_gatt_dsc_def[]) {
80+ {
81+ .uuid = &gatt_svr_dsc_uuid.u,
82+ .att_flags = BLE_ATT_F_READ,
83+ .access_cb = gatt_svc_access,
84+ }, {
85+ 0, /* No more descriptors in this characteristic */
86+ }
87+ },
88+ }, {
89+ 0, /* No more characteristics in this service. */
90+ }
91+ },
92+ },
93+ };
94+
95+ /* Add Extra service after Matter service */
96+ CHIP_ERROR err = chip::DeviceLayer::Internal::BLEMgrImpl().ConfigureExtraServices(gatt_svr_svcs, ture);
97+ }
98+ ```
99+
100+ Note: Extra service should be configure before ` InitServer ` .
101+
102+ ## Nimble: multiple BLE advertisement
103+
104+ The chips that support BLE 5.0 features can advertise their custom BLE GAP
105+ advertisement alongside Matter's BLE advertisement if ` CONFIG_BT_NIMBLE_EXT_ADV `
106+ is enabled and ` CONFIG_BT_NIMBLE_MAX_EXT_ADV_INSTANCES ` is a value greater
107+ than 1.
108+
109+ ### Usage
110+
111+ ```
112+ static uint8_t connectable_adv_pattern[] = {
113+ 0x02, 0x01, 0x06,
114+ 0x03, 0x03, 0xab, 0xcd,
115+ 0x03, 0x03, 0x18, 0x11,
116+ 0x12, 0X09, 'n', 'i', 'm', 'b', 'l', 'e', '-', 'c', 'o', 'n', 'n', 'e', 't', 'a', 'b', 'l', 'e'
117+ };
118+
119+ /* GAP event handler */
120+ static int ble_multi_adv_gap_event(struct ble_gap_event *event, void *arg);
121+
122+ {
123+ /* Use instance except 0 as Matter advertisement uses instance 0 */
124+ uint8_t instance = 1;
125+ struct ble_gap_ext_adv_params params;
126+ int size_pattern = sizeof(connectable_adv_pattern) / sizeof(connectable_adv_pattern[0]);
127+
128+ memset (¶ms, 0, sizeof(params));
129+
130+ params.connectable = 1;
131+ params.scannable = 1;
132+ params.own_addr_type = BLE_OWN_ADDR_RANDOM;
133+ params.sid = 1;
134+ params.primary_phy = BLE_HCI_LE_PHY_1M;
135+ params.secondary_phy = BLE_HCI_LE_PHY_1M;
136+ params.tx_power = 127;
137+
138+ int rc;
139+ struct os_mbuf *data;
140+ int size_pattern = sizeof(legacy_dur_adv_pattern) / sizeof(legacy_dur_adv_pattern[0]);
141+
142+ if (ble_gap_ext_adv_active(instance)) {
143+ ESP_LOGI(tag, "Instance already advertising");
144+ return;
145+ }
146+
147+ rc = ble_gap_ext_adv_configure(instance, params, NULL,
148+ ble_multi_adv_gap_event, NULL);
149+ assert (rc == 0);
150+
151+ /* get mbuf for adv data */
152+ data = os_msys_get_pkthdr(size_pattern, 0);
153+ assert(data);
154+
155+ /* fill mbuf with adv data */
156+ rc = os_mbuf_append(data, legacy_dur_adv_pattern, size_pattern);
157+ assert(rc == 0);
158+
159+ rc = ble_gap_ext_adv_set_data(instance, data);
160+ assert (rc == 0);
161+
162+ /* start advertising */
163+ rc = ble_gap_ext_adv_start(instance, 500, 0);
164+ assert (rc == 0);
165+ }
166+ ```
167+
168+ Note: The custom additional advertisement should be configured after BLE stack
169+ is started.
0 commit comments