Mistake on this page?
Report an issue in GitHub or email us
GattCharacteristic.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2013 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef __GATT_CHARACTERISTIC_H__
18 #define __GATT_CHARACTERISTIC_H__
19 
20 #include "ble/Gap.h"
21 #include "ble/SecurityManager.h"
22 #include "GattAttribute.h"
23 #include "GattCallbackParamTypes.h"
25 
26 /**
27  * @addtogroup ble
28  * @{
29  * @addtogroup gatt
30  * @{
31  * @addtogroup server
32  * @{
33  */
34 
35 /**
36  * Representation of a GattServer characteristic.
37  *
38  * A characteristic is a typed value enclosed in a GATT service (GattService).
39  *
40  * @par Type
41  *
42  * The type of the value defines the purpose of the characteristic, and a
43  * UUID represents it. Standard characteristic types may be consulted at
44  * https://www.bluetooth.com/specifications/gatt/characteristics
45  *
46  * @par Supported operations
47  * A set of properties define what client operations the characteristic
48  * supports. See GattServer::Properties_t
49  *
50  * @par Descriptors
51  *
52  * Additional information, such as the unit of the characteristic value, a
53  * description string or a client control point, can be added to the
54  * characteristic.
55  *
56  * See BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part G] - 3.3.1.1
57  *
58  * One of the most important types of descriptor is the Client Characteristic
59  * Configuration Descriptor (CCCD) that must be present if the characteristic
60  * properties allow a client to subscribe to updates of the characteristic
61  * value.
62  *
63  * @par Characteristic breakdown
64  *
65  * A characteristic is composed of several GATT attributes (GattAttribute):
66  * - Characteristic declaration: It contains the properties of the
67  * characteristic, its type and the handle of its value.
68  * - Characteristic value: The value of the characteristic.
69  * - Descriptors: A single GATT attribute stores each descriptor.
70  *
71  * When the GattService containing the characteristic is registered in the
72  * GattServer, a unique attribute handle is assigned to the various attributes
73  * of the characteristic. Clients use this handle to interact with the
74  * characteristic. This handle is used locally in GattServer APIs.
75  *
76  * @par Security requirements
77  *
78  * Verification of security requirements happens whenever a client request to
79  * read the characteristic; write it or even register to its updates. Different
80  * requirements may be defined for these three type of operation. As an example:
81  * it is possible to define a characteristic that do not require security to be
82  * read and require an authenticated link to be written.
83  *
84  * By default all security requirements are set to att_security_requirement_t::NONE
85  * except if the characteristic supports signed write; in such case the security
86  * requirement for write operations is set to att_security_requirement_t::UNAUTHENTICATED.
87  *
88  * @note If a peer uses an operation that is not set in the characteristic
89  * properties then the request request is discarded regardless of the security
90  * requirements and current security level. The only exception being signed
91  * write: signed write are converted into regular write without response if
92  * the link is encrypted.
93  */
95 public:
96 
97  /*
98  * Enumeration of characteristic UUID defined by the Bluetooth body.
99  */
100  enum {
101  /**
102  * Not used in actual BLE service.
103  */
105 
106  /**
107  * Not used in actual BLE service.
108  */
110 
111  /**
112  * Not used in actual BLE service.
113  */
115 
116  /**
117  * Not used in actual BLE service.
118  */
120 
121  /**
122  * Not used as a characteristic UUID.
123  */
125 
126  /**
127  * Not used as a characteristic UUID.
128  */
130 
131  /**
132  * Control point of the Immediate Alert service that allows the client to
133  * command the server to alert to a given level.
134  */
136 
137  /**
138  * Control point of the Alert Notification service that allows the client
139  * finely tune the notification configuration.
140  */
142 
143  /**
144  * Part of the Alert Notification service, which exposes the count of
145  * unread alert events existing in the server.
146  */
148 
149  /**
150  * Characteristic of the Battery service, which exposes the current
151  * battery level as a percentage.
152  */
154 
155  /**
156  * Describe the features supported by the blood pressure sensor exposed
157  * by the Blood Pressure service.
158  */
160 
161  /**
162  * Characteristic of the Blood Pressure service that exposes the
163  * measurement of the blood sensor.
164  */
166 
167  /**
168  * Characteristic of the Heart Rate service that indicate the intended
169  * location of the heart rate monitor.
170  */
172 
173  /**
174  * Part of the Human Interface Device service.
175  */
177 
178  /**
179  * Part of the Human Interface Device service.
180  */
182 
183  /**
184  * Part of the Human Interface Device service.
185  */
187 
188  /**
189  * Characteristic of the Current Time service that contains the current
190  * time.
191  */
193 
194  /**
195  * Not used in a service as a characteristic.
196  */
198 
199  /**
200  * Not used in a service as a characteristic.
201  */
203 
204  /**
205  * Not used in a service as a characteristic.
206  */
208 
209  /**
210  * Not used in a service as a characteristic.
211  */
213 
214  /**
215  * Not used in a service as a characteristic.
216  */
218 
219  /**
220  * Characteristic of the Device Information Service that contains a
221  * UTF8 string representing the firmware revision for the firmware within
222  * the device.
223  */
225 
226  /**
227  * Characteristic of the Glucose service that exposes features supported
228  * by the server.
229  */
231 
232  /**
233  * Characteristic of the Glucose service that exposes glucose
234  * measurements.
235  */
237 
238  /**
239  * Characteristic of the Glucose service that sends additional
240  * information related to the glucose measurements.
241  */
243 
244  /**
245  * Characteristic of the Device Information Service that contains a
246  * UTF8 string representing the hardware revision of the device.
247  */
249 
250  /**
251  * Characteristic of the Heart Rate service used by the client to control
252  * the service behavior.
253  */
255 
256  /**
257  * Characteristic of the Heart Rate that sends heart rate measurements to
258  * registered clients.
259  */
261 
262  /**
263  * Part of the Human Interface Device service.
264  */
266 
267  /**
268  * Part of the Human Interface Device service.
269  */
271 
272  /**
273  * Characteristic of the Environmental Sensing service, which exposes
274  * humidity measurements.
275  */
277 
278  /**
279  * Characteristic of the Device Information Service, which exposes
280  * various regulatory or certification compliance items to which the
281  * device claims adherence.
282  */
284 
285  /**
286  * Characteristic of the Blood Pressure service, which exposes intermediate
287  * cuff pressure measurements.
288  */
290 
291  /**
292  * Characteristic of the Health Thermometer service that sends intermediate
293  * temperature values while the measurement is in progress.
294  */
296 
297  /**
298  * Characteristic of the current Time service that exposes information
299  * about the local time.
300  */
302 
303  /**
304  * Characteristic of the Device Information Service that contains a
305  * UTF8 string representing the manufacturer name of the device.
306  */
308 
309  /**
310  * Characteristic of the Health Thermometer service that exposes the
311  * interval time between two measurements.
312  */
314 
315  /**
316  * Characteristic of the Device Information Service that contains a
317  * UTF8 string representing the model number of the device assigned by
318  * the vendor.
319  */
321 
322  /**
323  * Characteristic of the Alert Notification Service that shows how many
324  * numbers of unread alerts exist in the specific category in the device.
325  */
327 
328  /**
329  * Characteristic of the Alert Notification Service that defines the
330  * category of the alert and how many new alerts of that category have
331  * occurred in the server.
332  */
334 
335  /**
336  * Characteristic of the Device Information Service; it is a set of
337  * values used to create a device ID that is unique for this device.
338  */
340 
341  /**
342  * Characteristic of the Environmental Sensing Service that exposes the
343  * pressure measured.
344  */
346 
347  /**
348  * Part of the Human Interface Device service.
349  */
351 
352  /**
353  * Pulse Oxymeter, Glucose and Continuous Glucose Monitoring services
354  * use this control point to provide basic management of the patient
355  * record database.
356  */
358 
359  /**
360  * Characteristic of the Current Time service that exposes information
361  * related to the current time served (accuracy, source, hours since
362  * update and so on).
363  */
365 
366  /**
367  * Part of the Human Interface Device service.
368  */
370 
371  /**
372  * Part of the Human Interface Device service.
373  */
375 
376  /**
377  * Characteristic of the Phone Alert Status service that allows a client
378  * to configure operating mode.
379  */
381 
382  /**
383  * Characteristic of the Phone Alert Status service that returns the
384  * ringer setting when read.
385  */
387 
388  /**
389  * Characteristic of the Scan Parameter service that stores the client's
390  * scan parameters (scan interval and scan window).
391  */
393 
394  /**
395  * Characteristic of the Scan Parameter service that sends a notification
396  * to a client when the server requires its latest scan parameters.
397  */
399 
400  /**
401  * Characteristic of the Device Information Service that contains a
402  * UTF8 string representing the serial number of the device.
403  */
405 
406  /**
407  * Characteristic of the Device Information Service that contains an
408  * UTF8 string representing the software revision of the device.
409  */
411 
412  /**
413  * Characteristic of the Alert Notification Service that notifies the
414  * count of new alerts for a given category to a subscribed client.
415  */
417 
418  /**
419  * Characteristic of the Alert Notification service, which exposes
420  * categories of unread alert supported by the server.
421  */
423 
424  /**
425  * Characteristic of the Device Information Service that exposes a
426  * structure containing an Organizationally Unique Identifier (OUI)
427  * followed by a manufacturer-defined identifier. The value of the
428  * structure is unique for each individual instance of the product.
429  */
431 
432  /**
433  * Characteristic of the Environmental Sensing service that exposes the
434  * temperature measurement with a resolution of 0.01 degree Celsius.
435  */
437 
438  /**
439  * Characteristic of the Health Thermometer service that sends temperature
440  * measurement to clients.
441  */
443 
444  /**
445  * Characteristic of the Health Thermometer service that describes
446  * where the measurement takes place.
447  */
449 
450  /**
451  * Not used in a service as a characteristic.
452  */
454 
455  /**
456  * Not used in a service as a characteristic.
457  */
459 
460  /**
461  * Characteristic of the Reference Time service that allows clients to
462  * control time update.
463  */
465 
466  /**
467  * Characteristic of the Reference Time service that informs clients of
468  * the status of the time update operation.
469  */
471 
472  /**
473  * Characteristic of the Next DST Change service that returns to clients
474  * the time with DST.
475  */
477 
478  /**
479  * Not used in a service as a characteristic.
480  */
482 
483  /**
484  * Characteristic of the TX Power service that exposes the current
485  * transmission power in dBm.
486  */
488 
489  /**
490  * Characteristic of the Cycling Speed and Cadence (CSC) service that
491  * exposes features supported by the server.
492  */
494 
495  /**
496  * Characteristic of the Cycling Speed and Cadence (CSC) service that
497  * exposes measurements made by the server.
498  */
500 
501  /**
502  * Characteristic of the Running Speed and Cadence (RSC) service that
503  * exposes features supported by the server.
504  */
506 
507  /**
508  * Characteristic of the Running Speed and Cadence (RSC) service that
509  * exposes measurements made by the server.
510  */
512  };
513 
514  /**
515  * Unit type of a characteristic value.
516  *
517  * These unit types are used to describe what the raw numeric data in a
518  * characteristic actually represents. A server can expose that information
519  * to its clients by adding a Characteristic Presentation Format descriptor
520  * to relevant characteristics.
521  *
522  * @note See https://developer.bluetooth.org/gatt/units/Pages/default.aspx
523  */
524  enum {
525 
526  /**
527  * No specified unit type.
528  */
530 
531  /**
532  * Length, meter.
533  */
535 
536  /**
537  * Mass, kilogram.
538  */
540 
541  /**
542  * Time, second.
543  */
545 
546  /**
547  * Electric current, ampere.
548  */
550 
551  /**
552  * Thermodynamic temperature, kelvin.
553  */
555 
556  /** Amount of substance, mole.
557  *
558  */
560 
561  /**
562  * Luminous intensity, candela.
563  */
565 
566  /**
567  * Area, square meters.
568  */
570 
571  /**
572  * Volume, cubic meters.
573  */
575 
576  /**
577  * Velocity, meters per second.
578  */
580 
581  /**
582  * Acceleration, meters per second squared.
583  */
585 
586  /**
587  * Wave number reciprocal, meter.
588  */
590 
591  /**
592  * Density, kilogram per cubic meter.
593  */
595 
596  /**
597  * Surface density (kilogram per square meter).
598  */
600 
601  /**
602  * Specific volume (cubic meter per kilogram).
603  */
605 
606  /**
607  * Current density (ampere per square meter).
608  */
610 
611  /**
612  * Magnetic field strength, ampere per meter.
613  */
615 
616  /**
617  * Amount concentration (mole per cubic meter).
618  */
620 
621  /**
622  * Mass concentration (kilogram per cubic meter).
623  */
625 
626  /**
627  * Luminance (candela per square meter).
628  */
630 
631  /**
632  * Refractive index.
633  */
635 
636  /**
637  * Relative permeability.
638  */
640 
641  /**
642  * Plane angle (radian).
643  */
645 
646  /**
647  * Solid angle (steradian).
648  */
650 
651  /**
652  * Frequency, hertz.
653  */
655 
656  /**
657  * Force, newton.
658  */
660 
661  /**
662  * Pressure, pascal.
663  */
665 
666  /**
667  * Energy, joule.
668  */
670 
671  /**
672  * Power, watt.
673  */
675 
676  /**
677  * Electrical charge, coulomb.
678  */
680 
681  /**
682  * Electrical potential difference, voltage.
683  */
685 
686  /**
687  * Capacitance, farad.
688  */
690 
691  /**
692  * Electric resistance, ohm.
693  */
695 
696  /**
697  * Electric conductance, siemens.
698  */
700 
701  /**
702  * Magnetic flux, weber.
703  */
705 
706  /**
707  * Magnetic flux density, tesla.
708  */
710 
711  /**
712  * Inductance, henry.
713  */
715 
716  /**
717  * Celsius temperature, degree Celsius.
718  */
720 
721  /**
722  * Luminous flux, lumen.
723  */
725 
726  /**
727  * Illuminance, lux.
728  */
730 
731  /**
732  * Activity referred to a radionuclide, becquerel.
733  */
735 
736  /**
737  * Absorbed dose, gray.
738  */
740 
741  /**
742  * Dose equivalent, sievert.
743  */
745 
746  /**
747  * Catalytic activity, katal.
748  */
750 
751  /**
752  * Dynamic viscosity, pascal second.
753  */
755 
756  /**
757  * Moment of force, newton meter.
758  */
760 
761  /**
762  * Surface tension, newton per meter.
763  */
765 
766  /**
767  * Angular velocity, radian per second.
768  */
770 
771  /**
772  * Angular acceleration, radian per second squared.
773  */
775 
776  /**
777  * Heat flux density, watt per square meter.
778  */
780 
781  /**
782  * Heat capacity, joule per kelvin.
783  */
785 
786  /**
787  * Specific heat capacity, joule per kilogram kelvin.
788  */
790 
791  /**
792  * Specific energy, joule per kilogram.
793  */
795 
796  /**
797  * Thermal conductivity, watt per meter kelvin.
798  */
800 
801  /**
802  * Energy density, joule per cubic meter.
803  */
805 
806  /**
807  * Electric field strength, volt per meter.
808  */
810 
811  /**
812  * Electric charge density, coulomb per cubic meter.
813  */
815 
816  /**
817  * Surface charge density, coulomb per square meter.
818  */
820 
821  /**
822  * Electric flux density, coulomb per square meter.
823  */
825 
826  /**
827  * Permittivity, farad per meter.
828  */
830 
831  /**
832  * Permeability, henry per meter.
833  */
835 
836  /**
837  * Molar energy, joule per mole.
838  */
840 
841  /**
842  * Molar entropy, joule per mole kelvin.
843  */
845 
846  /**
847  * Exposure, coulomb per kilogram.
848  */
850 
851  /**
852  * Absorbed dose rate, gray per second.
853  */
855 
856  /**
857  * Radiant intensity, watt per steradian.
858  */
860 
861  /**
862  * Radiance, watt per square meter steradian.
863  */
865 
866  /**
867  * Catalytic activity concentration, katal per cubic meter.
868  */
870 
871  /**
872  * Time, minute.
873  */
875 
876  /**
877  * Time, hour.
878  */
880 
881  /**
882  * Time, day.
883  */
885 
886  /**
887  * Plane angle, degree.
888  */
890 
891  /**
892  * Plane angle, minute.
893  */
895 
896  /**
897  * Plane angle, seconds.
898  */
900 
901  /**
902  * Area, hectare.
903  */
905 
906  /**
907  * Volume, liter.
908  */
910 
911  /**
912  * Mass, ton.
913  */
915 
916  /**
917  * Pressure, bar.
918  */
920 
921  /**
922  * Pressure, millimeter of mercury.
923  */
925 
926  /**
927  * Length, ngstrm.
928  */
930 
931  /**
932  * Length, nautical mile.
933  */
935 
936  /**
937  * Area, barn.
938  */
940 
941  /**
942  * Velocity, knot.
943  */
945 
946  /**
947  * Logarithmic radio quantity, neper.
948  */
950 
951  /**
952  * Logarithmic radio quantity, bel.
953  */
955 
956  /**
957  * Length, yard.
958  */
960 
961  /**
962  * Length, parsec.
963  */
965 
966  /**
967  * Length, inch.
968  */
970 
971  /**
972  * Length, foot.
973  */
975 
976  /**
977  * Length, mile.
978  */
980 
981  /**
982  * Pressure, pound-force per square inch.
983  */
985 
986  /**
987  * Velocity, kilometer per hour.
988  */
990 
991  /** Velocity, mile per hour.
992  *
993  */
995 
996  /**
997  * Angular Velocity, revolution per minute.
998  */
1000 
1001  /**
1002  * Energy, gram calorie.
1003  */
1005 
1006  /**
1007  * Energy, kilogram calorie.
1008  */
1010 
1011  /**
1012  * Energy, killowatt hour.
1013  */
1015 
1016  /**
1017  * Thermodynamic temperature, degree Fahrenheit.
1018  */
1020 
1021  /**
1022  * Percentage.
1023  */
1025 
1026  /**
1027  * Per mille.
1028  */
1030 
1031  /**
1032  * Period, beats per minute.
1033  */
1035 
1036  /**
1037  * Electric charge, ampere hours.
1038  */
1040 
1041  /**
1042  * Mass density, milligram per deciliter.
1043  */
1045 
1046  /**
1047  * Mass density, millimole per liter.
1048  */
1050 
1051  /**
1052  * Time, year.
1053  */
1055 
1056  /**
1057  * Time, month.
1058  */
1060 
1061  /**
1062  * Concentration, count per cubic meter.
1063  */
1065 
1066  /**
1067  * Irradiance, watt per square meter.
1068  */
1070  };
1071 
1072  /**
1073  * Presentation format of a characteristic.
1074  *
1075  * It determines how the value of a characteristic is formatted. A server
1076  * can expose that information to its clients by adding a Characteristic
1077  * Presentation Format descriptor to relevant characteristics.
1078  *
1079  * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2.
1080  */
1081  enum {
1082  /**
1083  * Reserved for future use.
1084  */
1086 
1087  /**
1088  * Boolean.
1089  */
1091 
1092  /**
1093  * Unsigned 2-bit integer.
1094  */
1096 
1097  /**
1098  * Unsigned 4-bit integer.
1099  */
1101 
1102  /**
1103  * Unsigned 8-bit integer.
1104  */
1106 
1107  /**
1108  * Unsigned 12-bit integer.
1109  */
1111 
1112  /**
1113  * Unsigned 16-bit integer.
1114  */
1116 
1117  /**
1118  * Unsigned 24-bit integer.
1119  */
1121 
1122  /**
1123  * Unsigned 32-bit integer.
1124  */
1126 
1127  /**
1128  * Unsigned 48-bit integer.
1129  */
1131 
1132  /**
1133  * Unsigned 64-bit integer.
1134  */
1136 
1137  /**
1138  * Unsigned 128-bit integer.
1139  */
1141 
1142  /**
1143  * Signed 8-bit integer.
1144  */
1146 
1147  /**
1148  * Signed 12-bit integer.
1149  */
1151 
1152  /**
1153  * Signed 16-bit integer.
1154  */
1156 
1157  /**
1158  * Signed 24-bit integer.
1159  */
1161 
1162  /**
1163  * Signed 32-bit integer.
1164  */
1166 
1167  /**
1168  * Signed 48-bit integer.
1169  */
1171 
1172  /**
1173  * Signed 64-bit integer.
1174  */
1176 
1177  /**
1178  * Signed 128-bit integer.
1179  */
1181 
1182  /**
1183  * IEEE-754 32-bit floating point.
1184  */
1186 
1187  /**
1188  * IEEE-754 64-bit floating point.
1189  */
1191 
1192  /**
1193  * IEEE-11073 16-bit SFLOAT.
1194  */
1196 
1197  /**
1198  * IEEE-11073 32-bit FLOAT.
1199  */
1201 
1202  /**
1203  * IEEE-20601 format.
1204  */
1206 
1207  /**
1208  * UTF8 string.
1209  */
1211 
1212  /**
1213  * UTF16 string.
1214  */
1216 
1217  /**
1218  * Opaque Structure.
1219  */
1221  };
1222 
1223  /*!
1224  * Characteristic properties.
1225  *
1226  * It is a bitfield that determines how a characteristic value can be used.
1227  *
1228  * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.1.1
1229  * and Section 3.3.3.1 for Extended Properties.
1230  */
1232  /**
1233  * No property defined.
1234  */
1236 
1237  /**
1238  * Permits broadcasts of the characteristic value using the Server
1239  * Characteristic Configuration descriptor.
1240  */
1242 
1243  /**
1244  * Permits reads of the characteristic value.
1245  */
1247 
1248  /**
1249  * Permits writes of the characteristic value without response.
1250  */
1252 
1253  /**
1254  * Permits writes of the characteristic value with response.
1255  */
1257 
1258  /**
1259  * Permits notifications of a characteristic value without acknowledgment.
1260  */
1262 
1263  /**
1264  * Permits indications of a characteristic value with acknowledgment.
1265  */
1267 
1268  /**
1269  * Permits signed writes to the characteristic value.
1270  */
1272 
1273  /**
1274  * The Characteristic Extended Properties descriptor
1275  * defines additional characteristic properties.
1276  */
1278  };
1279 
1280  /**
1281  * Indicates if the properties has at least one of the writable flags.
1282  *
1283  * @param[in] properties The properties to inspect.
1284  *
1285  * @return True if the properties set at least one of the writable flags and
1286  * false otherwise.
1287  */
1288  static bool isWritable(uint8_t properties)
1289  {
1290  const uint8_t writable =
1294 
1295  return properties & writable;
1296  }
1297 
1298  /**
1299  * Indicates if the properties is readable.
1300  *
1301  * @param[in] properties The properties to inspect.
1302  *
1303  * @return True if the properties has its readable flag set and false
1304  * otherwise.
1305  */
1306  static bool isReadable(uint8_t properties)
1307  {
1308  const uint8_t readable = BLE_GATT_CHAR_PROPERTIES_READ;
1309  return properties & readable;
1310  }
1311 
1312  /**
1313  * Value of a Characteristic Presentation Format descriptor.
1314  *
1315  * Characteristic Presentation Format descriptor expresses the format of a
1316  * characteristic value.
1317  *
1318  * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.
1319  */
1321  /**
1322  * Format of the value.
1323  */
1324  uint8_t gatt_format;
1325 
1326  /**
1327  * Exponent for integer data types.
1328  *
1329  * Example: if Exponent = -3 and the char value is 3892, the actual
1330  * value is 3.892
1331  */
1332  int8_t exponent;
1333 
1334  /**
1335  * Unit of the characteristic value.
1336  *
1337  * It is a UUID from Bluetooth Assigned Numbers.
1338  */
1339  uint16_t gatt_unit;
1340 
1341  /**
1342  * Namespace of the description field.
1343  *
1344  * This field identifies the organization that is responsible for
1345  * defining the enumerations for the description field.
1346  *
1347  * The namespace of the Bluetooth Body is 0x01.
1348  */
1350 
1351  /**
1352  * Description.
1353  *
1354  * @note The value 0x0000 means unknown in the Bluetooth namespace.
1355  */
1356  uint16_t gatt_nsdesc;
1357 
1358  };
1359 
1360  /**
1361  * Security level applied to GATT operations.
1362  */
1364 
1365  /**
1366  * @brief Constructs a new GattCharacteristic.
1367  *
1368  * @param[in] uuid The UUID of this characteristic.
1369  * @param[in] valuePtr Memory buffer holding the initial value. The value is
1370  * copied into the Bluetooth subsytem when the enclosing service is added.
1371  * Thereafter, the stack maintains it internally.
1372  * @param[in] len The length in bytes of this characteristic's value.
1373  * @param[in] maxLen The capacity in bytes of the characteristic value
1374  * buffer.
1375  * @param[in] props An 8-bit field that contains the characteristic's
1376  * properties.
1377  * @param[in] descriptors A pointer to an array of descriptors to be included
1378  * within this characteristic. The caller owns the memory for the descriptor
1379  * array, which must remain valid at least until the enclosing service is
1380  * added to the GATT table.
1381  * @param[in] numDescriptors The number of descriptors presents in @p
1382  * descriptors array.
1383  * @param[in] hasVariableLen Flag that indicates if the attribute's value
1384  * length can change throughout time.
1385  *
1386  * @note If valuePtr is NULL, length is equal to 0 and the characteristic
1387  * is readable, then that particular characteristic may be considered
1388  * optional and dropped while instantiating the service with the underlying
1389  * BLE stack.
1390  *
1391  * @note A Client Characteristic Configuration Descriptor (CCCD) should not
1392  * be allocated if either the notify or indicate flag in the @p props bit
1393  * field; the underlying BLE stack handles it.
1394  *
1395  * @attention GattCharacteristic registered in a GattServer must remain
1396  * valid for the lifetime of the GattServer.
1397  */
1399  const UUID &uuid,
1400  uint8_t *valuePtr = NULL,
1401  uint16_t len = 0,
1402  uint16_t maxLen = 0,
1403  uint8_t props = BLE_GATT_CHAR_PROPERTIES_NONE,
1404  GattAttribute *descriptors[] = NULL,
1405  unsigned numDescriptors = 0,
1406  bool hasVariableLen = true
1407  ) : _valueAttribute(uuid, valuePtr, len, maxLen, hasVariableLen),
1408  _properties(props),
1409  _descriptors(descriptors),
1410  _descriptorCount(numDescriptors),
1411  readAuthorizationCallback(),
1412  writeAuthorizationCallback(),
1413  _update_security(SecurityRequirement_t::NONE) {
1414  _valueAttribute.allowWrite(isWritable(_properties));
1415  _valueAttribute.allowRead(isReadable(_properties));
1416 
1417 #if BLE_FEATURE_SECURITY
1418  // signed writes requires at least an unauthenticated CSRK or an
1419  // unauthenticated ltk if the link is encrypted.
1421  _valueAttribute.setWriteSecurityRequirement(
1423  );
1424  }
1425 #endif // BLE_FEATURE_SECURITY
1426  }
1427 
1428 public:
1429  /**
1430  * Set up the minimum security (mode and level) requirements for access to
1431  * the characteristic's value attribute.
1432  *
1433  * @param[in] securityMode Can be one of encryption or signing, with or
1434  * without protection for man in the middle attacks (MITM).
1435  *
1436  * @deprecated Fine grained security check has been added to with mbed OS
1437  * 5.9. It is possible to set independently security requirements for read,
1438  * write and update operations. In the meantime SecurityManager::SecurityMode_t
1439  * is not used anymore to represent security requirements as it maps
1440  * incorrectly the Bluetooth standard.
1441  */
1443  "mbed-os-5.9",
1444  "Use setWriteSecurityRequirements, setReadSecurityRequirements and "
1445  "setUpdateSecurityRequirements"
1446  )
1447  void requireSecurity(SecurityManager::SecurityMode_t securityMode)
1448  {
1449  SecurityRequirement_t sec_requirements = SecurityModeToAttSecurity(securityMode);
1450 
1451  _valueAttribute.setReadSecurityRequirement(sec_requirements);
1452  _valueAttribute.setWriteSecurityRequirement(sec_requirements);
1453  _update_security = sec_requirements.value();
1454  }
1455 
1456  /**
1457  * Set all security requirements of the characteristic.
1458  *
1459  * @param read_security The security requirement of the read operations.
1460  * @param write_security The security requirement of write operations.
1461  * @param update_security The security requirement of update operations.
1462  */
1464  SecurityRequirement_t read_security,
1465  SecurityRequirement_t write_security,
1466  SecurityRequirement_t update_security
1467  ) {
1468  setReadSecurityRequirement(read_security);
1469  setWriteSecurityRequirement(write_security);
1470  setUpdateSecurityRequirement(update_security);
1471  }
1472 
1473  /**
1474  * Set the security of the read operation.
1475  *
1476  * @param[in] security The security requirement of the read operation.
1477  */
1479  {
1480  _valueAttribute.setReadSecurityRequirement(security);
1481  }
1482 
1483  /**
1484  * Get the security requirement of the read operation.
1485  *
1486  * @return The security requirement of the read operation.
1487  */
1489  {
1490  return _valueAttribute.getReadSecurityRequirement();
1491  }
1492 
1493  /**
1494  * Set the security requirement of the write operations.
1495  *
1496  * @note If the signed write flag is set in the characteristic properties
1497  * then the security requirement applied to write operation must be either
1498  * AUTHENTICATED or UNAUTHENTICATED. Security requirements NONE and
1499  * SC_AUTHENTICATED are not applicable to signing operation.
1500  *
1501  * @param[in] security The security requirement of write operations.
1502  */
1504  {
1505 #if BLE_FEATURE_SECURITY
1506  MBED_ASSERT(
1508  ((security == SecurityRequirement_t::NONE) ||
1509  (security == SecurityRequirement_t::SC_AUTHENTICATED))) == false
1510  );
1511 #endif // BLE_FEATURE_SECURITY
1512  _valueAttribute.setWriteSecurityRequirement(security);
1513  }
1514 
1515  /**
1516  * Get the security requirement of write operations.
1517  *
1518  * @return The security requirement of write operations.
1519  */
1521  {
1522  return _valueAttribute.getWriteSecurityRequirement();
1523  }
1524 
1525  /**
1526  * Set the security requirement of update operations.
1527  *
1528  * @note This security requirement is also applied to the write operation of
1529  * the Client Characteristic Configuration Descriptor.
1530  *
1531  * @param[in] security The security requirement that must be met to send
1532  * updates and accept write of the CCCD.
1533  */
1535  {
1536  _update_security = security.value();
1537  }
1538 
1539  /**
1540  * Get the security requirement of update operations.
1541  *
1542  * @note This security requirement is also applied to the write operation of
1543  * the Client Characteristic Configuration Descriptor.
1544  *
1545  * @return The security requirement that must be met to send updates and
1546  * accept write of the CCCD.
1547  */
1549  {
1550  return static_cast<SecurityRequirement_t::type>(_update_security);
1551  }
1552 
1553 public:
1554  /**
1555  * Register a callback handling client's write requests or commands.
1556  *
1557  * The callback registered is invoked when the client attempts to write the
1558  * characteristic value; the event handler can accept or reject the write
1559  * request with the appropriate error code.
1560  *
1561  * @param[in] callback Event handler being registered.
1562  */
1565  ) {
1566  writeAuthorizationCallback.attach(callback);
1567  }
1568 
1569  /**
1570  * Register a callback handling client's write requests or commands.
1571  *
1572  * The callback registered is invoked when the client attempts to write the
1573  * characteristic value; the event handler can accept or reject the write
1574  * request with the appropriate error code.
1575  *
1576  * @param[in] object Pointer to the object of a class defining the event
1577  * handler (@p member). It must remain valid for the lifetime of the
1578  * GattCharacteristic.
1579  * @param[in] member The member function that handles the write event.
1580  */
1581  template <typename T>
1583  T *object,
1584  void (T::*member)(GattWriteAuthCallbackParams *)
1585  ) {
1586  writeAuthorizationCallback.attach(object, member);
1587  }
1588 
1589  /**
1590  * Register the read requests event handler.
1591  *
1592  * The callback registered is invoked when the client attempts to read the
1593  * characteristic value; the event handler can accept or reject the read
1594  * request with the appropriate error code. It can also set specific outgoing
1595  * data.
1596  *
1597  * @param[in] callback Event handler being registered.
1598  */
1601  ) {
1602  readAuthorizationCallback.attach(callback);
1603  }
1604 
1605  /**
1606  * Register the read requests event handler.
1607  *
1608  * The callback registered is invoked when the client attempts to read the
1609  * characteristic value; the event handler can accept or reject the read
1610  * request with the appropriate error code. It can also set specific outgoing
1611  * data.
1612  *
1613  * @param[in] object Pointer to the object of a class defining the event
1614  * handler (@p member). It must remain valid for the lifetime of the
1615  * GattCharacteristic.
1616  * @param[in] member The member function that handles the read event.
1617  */
1618  template <typename T>
1620  T *object,
1621  void (T::*member)(GattReadAuthCallbackParams *)
1622  ) {
1623  readAuthorizationCallback.attach(object, member);
1624  }
1625 
1626  /**
1627  * Invoke the write authorization callback.
1628  *
1629  * This function is a helper that calls the registered write handler to
1630  * determine the authorization reply for a write request.
1631  *
1632  * @attention This function is not meant to be called by user code.
1633  *
1634  * @param[in] params Context of the write-auth request; it contains an
1635  * out-parameter used as a reply.
1636  *
1637  * @return A GattAuthCallbackReply_t value indicating whether authorization
1638  * is granted.
1639  */
1641  {
1642  if (!isWriteAuthorizationEnabled()) {
1644  }
1645 
1646  /* Initialized to no-error by default. */
1648  writeAuthorizationCallback.call(params);
1649  return params->authorizationReply;
1650  }
1651 
1652  /**
1653  * Invoke the read authorization callback.
1654  *
1655  * This function is a helper that calls the registered read handler to
1656  * determine the authorization reply for a read request.
1657  *
1658  * @attention This function is not meant to be called by user code.
1659  *
1660  * @param[in] params Context of the read-auth request; it contains an
1661  * out-parameter used as a reply and the handler can fill it with outgoing
1662  * data.
1663  *
1664  * @return A GattAuthCallbackReply_t value indicating whether authorization
1665  * is granted.
1666  *
1667  * @note If the read request is approved and params->data remains NULL, then
1668  * the current characteristic value is used in the read response payload.
1669  *
1670  * @note If the read is approved, the event handler can specify an outgoing
1671  * value directly with the help of the fields
1672  * GattReadAuthCallbackParams::data and GattReadAuthCallbackParams::len.
1673  */
1675  {
1676  if (!isReadAuthorizationEnabled()) {
1678  }
1679 
1680  /* Initialized to no-error by default. */
1682  readAuthorizationCallback.call(params);
1683  return params->authorizationReply;
1684  }
1685 
1686 public:
1687  /**
1688  * Get the characteristic's value attribute.
1689  *
1690  * @return A reference to the characteristic's value attribute.
1691  */
1693  {
1694  return _valueAttribute;
1695  }
1696 
1697  /**
1698  * Get the characteristic's value attribute.
1699  *
1700  * @return A const reference to the characteristic's value attribute.
1701  */
1703  {
1704  return _valueAttribute;
1705  }
1706 
1707  /**
1708  * Get the characteristic's value attribute handle in the ATT table.
1709  *
1710  * @return The value attribute handle.
1711  *
1712  * @note The underlying BLE stack assigns the attribute handle when the
1713  * enclosing service is added.
1714  */
1716  {
1717  return getValueAttribute().getHandle();
1718  }
1719 
1720  /**
1721  * Get the characteristic's properties.
1722  *
1723  * @note Refer to GattCharacteristic::Properties_t.
1724  *
1725  * @return The characteristic's properties.
1726  */
1727  uint8_t getProperties(void) const
1728  {
1729  return _properties;
1730  }
1731 
1732  /**
1733  * Get the characteristic's required security.
1734  *
1735  * @return The characteristic's required security.
1736  *
1737  * @deprecated Fine grained security check has been added to with mbed OS
1738  * 5.9. It is possible to set independently security requirements for read,
1739  * write and update operations. In the meantime SecurityManager::SecurityMode_t
1740  * is not used anymore to represent security requirements as it maps
1741  * incorrectly the Bluetooth standard.
1742  */
1744  "mbed-os-5.9",
1745  "Use getWriteSecurityRequirements, getReadSecurityRequirements and "
1746  "getUpdateSecurityRequirements"
1747  )
1748  SecurityManager::SecurityMode_t getRequiredSecurity() const
1749  {
1750  SecurityRequirement_t max_sec = std::max(
1751  std::max(
1754  ),
1756  );
1757 
1758  bool needs_signing =
1760 
1761  switch(max_sec.value()) {
1763  MBED_ASSERT(needs_signing == false);
1765 #if BLE_FEATURE_SECURITY
1767  return (needs_signing) ?
1770 
1772  return (needs_signing) ?
1775 #if BLE_FEATURE_SECURE_CONNECTIONS
1777  MBED_ASSERT(needs_signing == false);
1778  // fallback to encryption with MITM
1780 #endif // BLE_FEATURE_SECURE_CONNECTIONS
1781 #endif // BLE_FEATURE_SECURITY
1782  default:
1783  MBED_ASSERT(false);
1784  return SecurityManager::SECURITY_MODE_NO_ACCESS;
1785  }
1786  }
1787 
1788  /**
1789  * Get the total number of descriptors within this characteristic.
1790  *
1791  * @return The total number of descriptors.
1792  */
1793  uint8_t getDescriptorCount(void) const
1794  {
1795  return _descriptorCount;
1796  }
1797 
1798  /**
1799  * Check whether read authorization is enabled.
1800  *
1801  * Read authorization is enabled when a read authorization event handler is
1802  * set up.
1803  *
1804  * @return true if read authorization is enabled and false otherwise.
1805  */
1807  {
1808  return readAuthorizationCallback;
1809  }
1810 
1811  /**
1812  * Check whether write authorization is enabled.
1813  *
1814  * Write authorization is enabled when a write authorization event handler is
1815  * set up.
1816  *
1817  * @return true if write authorization is enabled, false otherwise.
1818  */
1820  {
1821  return writeAuthorizationCallback;
1822  }
1823 
1824  /**
1825  * Get this characteristic's descriptor at a specific index.
1826  *
1827  * @param[in] index The index of the descriptor to get.
1828  *
1829  * @return A pointer the requested descriptor if @p index is within the
1830  * range of the descriptor array or NULL otherwise.
1831  */
1833  {
1834  if (index >= _descriptorCount) {
1835  return NULL;
1836  }
1837 
1838  return _descriptors[index];
1839  }
1840 
1841 private:
1842 
1843  /**
1844  * Loosely convert a SecurityManager::SecurityMode_t into a
1845  * SecurityRequirement_t.
1846  *
1847  * @param[in] mode The security mode to convert
1848  *
1849  * @return The security requirement equivalent to the security mode in input.
1850  */
1851  SecurityRequirement_t SecurityModeToAttSecurity(
1853  ) {
1854  switch(mode) {
1856  case SecurityManager::SECURITY_MODE_NO_ACCESS:
1857  // assuming access is managed by property and orthogonal to
1858  // security mode ...
1860 #if BLE_FEATURE_SECURITY
1862 #if BLE_FEATURE_SIGNING
1864 #endif
1866 
1868 #if BLE_FEATURE_SIGNING
1870 #endif
1872 #endif // BLE_FEATURE_SECURITY
1873  default:
1874  // should not happens; makes the compiler happy.
1876  }
1877  }
1878 
1879  /**
1880  * Attribute that contains the actual value of this characteristic.
1881  */
1882  GattAttribute _valueAttribute;
1883 
1884  /**
1885  * The characteristic's properties. Refer to
1886  * GattCharacteristic::Properties_t.
1887  */
1888  uint8_t _properties;
1889 
1890  /**
1891  * The characteristic's descriptor attributes.
1892  */
1893  GattAttribute **_descriptors;
1894 
1895  /**
1896  * The number of descriptors in this characteristic.
1897  */
1898  uint8_t _descriptorCount;
1899 
1900  /**
1901  * The registered callback handler for read authorization reply.
1902  */
1904  readAuthorizationCallback;
1905 
1906  /**
1907  * The registered callback handler for write authorization reply.
1908  */
1910  writeAuthorizationCallback;
1911 
1912  /**
1913  * Security requirements of update operations.
1914  *
1915  * The peer must meet the security requirement to enable, disable and
1916  * receive updates
1917  */
1918  uint8_t _update_security: SecurityRequirement_t::size;
1919 
1920 private:
1921  /* Disallow copy and assignment. */
1923  GattCharacteristic& operator=(const GattCharacteristic &);
1924 };
1925 
1926 /**
1927  * Helper class that represents a read only GattCharacteristic.
1928  */
1929 template <typename T>
1931 public:
1932  /**
1933  * Construct a ReadOnlyGattCharacteristic.
1934  *
1935  * @param[in] uuid The characteristic's UUID.
1936  * @param[in] valuePtr Pointer to the characteristic's initial value. The
1937  * pointer is reinterpreted as a pointer to an uint8_t buffer.
1938  * @param[in] additionalProperties Additional characteristic properties. By
1939  * default, the properties are set to
1940  * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
1941  * @param[in] descriptors An array of pointers to descriptors to be added
1942  * to the new characteristic.
1943  * @param[in] numDescriptors The total number of descriptors in @p
1944  * descriptors.
1945  *
1946  * @note Instances of ReadOnlyGattCharacteristic have a fixed length
1947  * attribute value that equals sizeof(T). For a variable length alternative,
1948  * use GattCharacteristic directly.
1949  */
1951  const UUID &uuid,
1952  T *valuePtr,
1953  uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
1954  GattAttribute *descriptors[] = NULL,
1955  unsigned numDescriptors = 0
1956  ) : GattCharacteristic(
1957  uuid,
1958  reinterpret_cast<uint8_t *>(valuePtr),
1959  sizeof(T),
1960  sizeof(T),
1961  BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties,
1962  descriptors,
1963  numDescriptors,
1964  false
1965  ) {
1966  }
1967 };
1968 
1969 /**
1970  * Helper class that represents a write only GattCharacteristic.
1971  */
1972 template <typename T>
1974 public:
1975  /**
1976  * Construct a WriteOnlyGattCharacteristic.
1977  *
1978  * @param[in] uuid The characteristic's UUID.
1979  * @param[in] valuePtr Pointer to the characteristic's initial value. The
1980  * pointer is reinterpreted as a pointer to an uint8_t buffer.
1981  * @param[in] additionalProperties Additional characteristic properties. By
1982  * default, the properties are set to
1983  * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
1984  * @param[in] descriptors An array of pointers to descriptors to be added to
1985  * the new characteristic.
1986  * @param[in] numDescriptors The total number of descriptors in @p
1987  * descriptors.
1988  *
1989  * @note Instances of WriteOnlyGattCharacteristic have variable length
1990  * attribute value with maximum size equal to sizeof(T). For a fixed length
1991  * alternative, use GattCharacteristic directly.
1992  */
1994  const UUID &uuid,
1995  T *valuePtr,
1996  uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
1997  GattAttribute *descriptors[] = NULL,
1998  unsigned numDescriptors = 0
1999  ) : GattCharacteristic(
2000  uuid,
2001  reinterpret_cast<uint8_t *>(valuePtr),
2002  sizeof(T),
2003  sizeof(T),
2004  BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
2005  descriptors,
2006  numDescriptors
2007  ) {
2008  }
2009 };
2010 
2011 /**
2012  * Helper class that represents a readable and writable GattCharacteristic.
2013  */
2014 template <typename T>
2016 public:
2017  /**
2018  * Construct a ReadWriteGattCharacteristic.
2019  *
2020  * @param[in] uuid The characteristic's UUID.
2021  * @param[in] valuePtr Pointer to the characteristic's initial value. The
2022  * pointer is reinterpreted as a pointer to an uint8_t buffer.
2023  * @param[in] additionalProperties Additional characteristic properties. By
2024  * default, the properties are set to
2025  * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE and
2026  * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
2027  * @param[in] descriptors An array of pointers to descriptors to be added to
2028  * the new characteristic.
2029  * @param[in] numDescriptors The total number of descriptors in @p descriptors.
2030  *
2031  * @note Instances of ReadWriteGattCharacteristic have variable length
2032  * attribute value with maximum size equal to sizeof(T). For a fixed length
2033  * alternative, use GattCharacteristic directly.
2034  */
2036  const UUID &uuid,
2037  T *valuePtr,
2038  uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
2039  GattAttribute *descriptors[] = NULL,
2040  unsigned numDescriptors = 0
2041  ) : GattCharacteristic(
2042  uuid,
2043  reinterpret_cast<uint8_t *>(valuePtr),
2044  sizeof(T),
2045  sizeof(T),
2047  descriptors,
2048  numDescriptors
2049  ) {
2050  }
2051 };
2052 
2053 /**
2054  * Helper class that represents a write-only GattCharacteristic with an array
2055  * value.
2056  */
2057 template <typename T, unsigned NUM_ELEMENTS>
2059 public:
2060  /**
2061  * Construct a WriteOnlyGattCharacteristic.
2062  *
2063  * @param[in] uuid The characteristic's UUID.
2064  * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
2065  * the characteristic's initial value. The pointer is reinterpreted as a
2066  * pointer to an uint8_t buffer.
2067  * @param[in] additionalProperties Additional characteristic properties. By
2068  * default, the properties are set to
2069  * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
2070  * @param[in] descriptors An array of pointers to descriptors to be added to
2071  * the new characteristic.
2072  * @param[in] numDescriptors The total number of descriptors in @p descriptors.
2073  *
2074  * @note Instances of WriteOnlyGattCharacteristic have variable length
2075  * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS.
2076  * For a fixed length alternative, use GattCharacteristic directly.
2077  */
2079  const UUID &uuid,
2080  T valuePtr[NUM_ELEMENTS],
2081  uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
2082  GattAttribute *descriptors[] = NULL,
2083  unsigned numDescriptors = 0
2084  ) : GattCharacteristic(
2085  uuid,
2086  reinterpret_cast<uint8_t *>(valuePtr),
2087  sizeof(T) * NUM_ELEMENTS,
2088  sizeof(T) * NUM_ELEMENTS,
2089  BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
2090  descriptors,
2091  numDescriptors
2092  ) {
2093  }
2094 };
2095 
2096 /**
2097  * Helper class that represents a read-only GattCharacteristic with an array
2098  * value.
2099  */
2100 template <typename T, unsigned NUM_ELEMENTS>
2102 public:
2103  /**
2104  * Construct a ReadOnlyGattCharacteristic.
2105  *
2106  * @param[in] uuid The characteristic's UUID.
2107  * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
2108  * the characteristic's initial value. The pointer is reinterpreted as a
2109  * pointer to an uint8_t buffer.
2110  * @param[in] additionalProperties Additional characteristic properties. By
2111  * default, the properties are set to
2112  * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
2113  * @param[in] descriptors An array of pointers to descriptors to be added to
2114  * the new characteristic.
2115  * @param[in] numDescriptors The total number of descriptors in @p
2116  * descriptors.
2117  *
2118  * @note Instances of ReadOnlyGattCharacteristic have fixed length
2119  * attribute value that equals sizeof(T) * NUM_ELEMENTS. For a variable
2120  * length alternative, use GattCharacteristic directly.
2121  */
2123  const UUID &uuid,
2124  T valuePtr[NUM_ELEMENTS],
2125  uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
2126  GattAttribute *descriptors[] = NULL,
2127  unsigned numDescriptors = 0
2128  ) : GattCharacteristic(
2129  uuid,
2130  reinterpret_cast<uint8_t *>(valuePtr),
2131  sizeof(T) * NUM_ELEMENTS,
2132  sizeof(T) * NUM_ELEMENTS,
2133  BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties,
2134  descriptors,
2135  numDescriptors,
2136  false
2137  ) {
2138  }
2139 };
2140 
2141 /**
2142  * Helper class that represents a readable and writable GattCharacteristic with
2143  * an array value.
2144  */
2145 template <typename T, unsigned NUM_ELEMENTS>
2147 public:
2148  /**
2149  * Construct a ReadWriteGattCharacteristic.
2150  *
2151  * @param[in] uuid The characteristic's UUID.
2152  * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
2153  * the characteristic's initial value. The pointer is reinterpreted as a
2154  * pointer to an uint8_t buffer.
2155  * @param[in] additionalProperties Additional characteristic properties. By
2156  * default, the properties are set to
2157  * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
2158  * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
2159  * @param[in] descriptors An array of pointers to descriptors to be added to
2160  * the new characteristic.
2161  * @param[in] numDescriptors The total number of descriptors in @p descriptors.
2162  *
2163  * @note Instances of ReadWriteGattCharacteristic have variable length
2164  * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS.
2165  * For a fixed length alternative, use GattCharacteristic directly.
2166  */
2168  const UUID &uuid,
2169  T valuePtr[NUM_ELEMENTS],
2170  uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
2171  GattAttribute *descriptors[] = NULL,
2172  unsigned numDescriptors = 0
2173  ) : GattCharacteristic(
2174  uuid,
2175  reinterpret_cast<uint8_t *>(valuePtr),
2176  sizeof(T) * NUM_ELEMENTS,
2177  sizeof(T) * NUM_ELEMENTS,
2179  descriptors,
2180  numDescriptors
2181  ) {
2182  }
2183 };
2184 
2185 /**
2186  * @}
2187  * @}
2188  * @}
2189  */
2190 
2191 #endif /* ifndef __GATT_CHARACTERISTIC_H__ */
Part of the Human Interface Device service.
Not used in a service as a characteristic.
Helper class that represents a readable and writable GattCharacteristic.
Characteristic of the Device Information Service; it is a set of values used to create a device ID th...
Characteristic of the Glucose service that sends additional information related to the glucose measur...
Characteristic of the Glucose service that exposes glucose measurements.
Characteristic of the Health Thermometer service that exposes the interval time between two measureme...
Permits reads of the characteristic value.
GattAuthCallbackReply_t authorizationReply
Authorization result.
Characteristic of the Current Time service that exposes information related to the current time serve...
Characteristic of the Next DST Change service that returns to clients the time with DST...
uint8_t getProperties(void) const
Get the characteristic&#39;s properties.
Characteristic of the Blood Pressure service that exposes the measurement of the blood sensor...
void requireSecurity(SecurityManager::SecurityMode_t securityMode)
Set up the minimum security (mode and level) requirements for access to the characteristic&#39;s value at...
Part of the Human Interface Device service.
Part of the Alert Notification service, which exposes the count of unread alert events existing in th...
static bool isWritable(uint8_t properties)
Indicates if the properties has at least one of the writable flags.
uint8_t gatt_namespace
Namespace of the description field.
Characteristic of the Environmental Sensing service that exposes the temperature measurement with a r...
GattAuthCallbackReply_t authorizeRead(GattReadAuthCallbackParams *params)
Invoke the read authorization callback.
Not used in a service as a characteristic.
GATT write authorization request event.
Characteristic of the Alert Notification service, which exposes categories of unread alert supported ...
SecurityRequirement_t getReadSecurityRequirement() const
Get the security requirement of the read operation.
The operation require encryption with an authenticated peer that paired using secure connection pairi...
Definition: BLETypes.h:567
Characteristic of the Blood Pressure service, which exposes intermediate cuff pressure measurements...
Characteristic of the Health Thermometer service that describes where the measurement takes place...
Characteristic of the Heart Rate service used by the client to control the service behavior...
void setUpdateSecurityRequirement(SecurityRequirement_t security)
Set the security requirement of update operations.
Characteristic of the Running Speed and Cadence (RSC) service that exposes features supported by the ...
Security requirement that can be attached to an attribute operation.
Definition: BLETypes.h:512
void setSecurityRequirements(SecurityRequirement_t read_security, SecurityRequirement_t write_security, SecurityRequirement_t update_security)
Set all security requirements of the characteristic.
The operation requires security and there&#39;s no requirement towards peer authentication.
Definition: BLETypes.h:547
Part of the Human Interface Device service.
Helper class that represents a readable and writable GattCharacteristic with an array value...
ble::att_security_requirement_t SecurityRequirement_t
Security level applied to GATT operations.
GATT read authorization request event.
GattAttribute & getValueAttribute()
Get the characteristic&#39;s value attribute.
Permits notifications of a characteristic value without acknowledgment.
Require signing or encryption, but no MITM protection.
Not used in a service as a characteristic.
GattAuthCallbackReply_t authorizationReply
Authorization result.
uint8_t getDescriptorCount(void) const
Get the total number of descriptors within this characteristic.
LayoutType value() const
Explicit access to the inner value of the SafeEnum instance.
Definition: SafeEnum.h:202
const GattAttribute & getValueAttribute() const
Get the characteristic&#39;s value attribute.
Characteristic of the Reference Time service that allows clients to control time update.
The operation does not have security requirements.
Definition: BLETypes.h:533
Not used in a service as a characteristic.
Characteristic of the Device Information Service that exposes a structure containing an Organizationa...
Characteristic of the Environmental Sensing service, which exposes humidity measurements.
Require signing or encryption, and MITM protection.
type
struct scoped enum wrapped by the class
Definition: BLETypes.h:522
Describe the features supported by the blood pressure sensor exposed by the Blood Pressure service...
Characteristic of the Device Information Service that contains a UTF8 string representing the firmwar...
uint8_t gatt_format
Format of the value.
Callback< R()> callback(R(*func)()=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:3848
Helper class that represents a read-only GattCharacteristic with an array value.
Representation of a Universally Unique Identifier (UUID).
Definition: UUID.h:74
void setReadSecurityRequirement(SecurityRequirement_t security)
Set the security of the read operation.
Representation of a GattServer attribute.
Definition: GattAttribute.h:58
Not used in a service as a characteristic.
Characteristic of the Device Information Service that contains an UTF8 string representing the softwa...
Characteristic of the Scan Parameter service that sends a notification to a client when the server re...
Characteristic of the Health Thermometer service that sends temperature measurement to clients...
Characteristic of the Device Information Service that contains a UTF8 string representing the manufac...
Characteristic of the Running Speed and Cadence (RSC) service that exposes measurements made by the s...
Permits writes of the characteristic value without response.
Characteristic of the Scan Parameter service that stores the client&#39;s scan parameters (scan interval ...
ble::attribute_handle_t Handle_t
Representation of an attribute handle.
Definition: GattAttribute.h:67
Require encryption, but no MITM protection.
Characteristic of the Phone Alert Status service that allows a client to configure operating mode...
Characteristic of the Device Information Service that contains a UTF8 string representing the hardwar...
Helper class that represents a write-only GattCharacteristic with an array value. ...
int8_t exponent
Exponent for integer data types.
GattCharacteristic(const UUID &uuid, uint8_t *valuePtr=NULL, uint16_t len=0, uint16_t maxLen=0, uint8_t props=BLE_GATT_CHAR_PROPERTIES_NONE, GattAttribute *descriptors[]=NULL, unsigned numDescriptors=0, bool hasVariableLen=true)
Constructs a new GattCharacteristic.
Part of the Human Interface Device service.
Characteristic of the Cycling Speed and Cadence (CSC) service that exposes measurements made by the s...
Handle_t getHandle(void) const
Get the attribute&#39;s handle in the ATT table.
void setReadAuthorizationCallback(void(*callback)(GattReadAuthCallbackParams *))
Register the read requests event handler.
bool isReadAuthorizationEnabled() const
Check whether read authorization is enabled.
Characteristic of the Heart Rate service that indicate the intended location of the heart rate monito...
GattAuthCallbackReply_t authorizeWrite(GattWriteAuthCallbackParams *params)
Invoke the write authorization callback.
#define MBED_ASSERT(expr)
MBED_ASSERT Declare runtime assertions: results in runtime error if condition is false.
Definition: mbed_assert.h:65
Characteristic of the Phone Alert Status service that returns the ringer setting when read...
Characteristic of the Cycling Speed and Cadence (CSC) service that exposes features supported by the ...
SecurityMode_t
level of security required from the link by the application
static const uint8_t size
Number of bits required to store the value.
Definition: BLETypes.h:519
Not used in actual BLE service.
Characteristic of the Current Time service that contains the current time.
static bool isReadable(uint8_t properties)
Indicates if the properties is readable.
Not used in a service as a characteristic.
SecurityRequirement_t getWriteSecurityRequirement() const
Get the security requirement of write operations.
The Characteristic Extended Properties descriptor defines additional characteristic properties...
Characteristic of the Health Thermometer service that sends intermediate temperature values while the...
Representation of a GattServer characteristic.
Not used in a service as a characteristic.
Characteristic of the current Time service that exposes information about the local time...
GattAttribute * getDescriptor(uint8_t index)
Get this characteristic&#39;s descriptor at a specific index.
Permits indications of a characteristic value with acknowledgment.
Require encryption and MITM protection.
Characteristic of the Battery service, which exposes the current battery level as a percentage...
Helper class that represents a write only GattCharacteristic.
Control point of the Alert Notification service that allows the client finely tune the notification c...
Characteristic of the TX Power service that exposes the current transmission power in dBm...
uint16_t gatt_unit
Unit of the characteristic value.
GattAttribute::Handle_t getValueHandle(void) const
Get the characteristic&#39;s value attribute handle in the ATT table.
Characteristic of the Device Information Service that contains a UTF8 string representing the serial ...
Part of the Human Interface Device service.
Permits broadcasts of the characteristic value using the Server Characteristic Configuration descript...
Characteristic of the Alert Notification Service that notifies the count of new alerts for a given ca...
bool isWriteAuthorizationEnabled() const
Check whether write authorization is enabled.
SecurityRequirement_t getUpdateSecurityRequirement() const
Get the security requirement of update operations.
Characteristic of the Alert Notification Service that shows how many numbers of unread alerts exist i...
void setReadAuthorizationCallback(T *object, void(T::*member)(GattReadAuthCallbackParams *))
Register the read requests event handler.
void setWriteAuthorizationCallback(void(*callback)(GattWriteAuthCallbackParams *))
Register a callback handling client&#39;s write requests or commands.
Part of the Human Interface Device service.
Characteristic of the Alert Notification Service that defines the category of the alert and how many ...
void setWriteSecurityRequirement(SecurityRequirement_t security)
Set the security requirement of the write operations.
The operation requires security and the peer must be authenticated.
Definition: BLETypes.h:558
Characteristic of the Heart Rate that sends heart rate measurements to registered clients...
Characteristic of the Glucose service that exposes features supported by the server.
Characteristic of the Reference Time service that informs clients of the status of the time update op...
void setWriteAuthorizationCallback(T *object, void(T::*member)(GattWriteAuthCallbackParams *))
Register a callback handling client&#39;s write requests or commands.
Helper class that represents a read only GattCharacteristic.
Characteristic of the Device Information Service that contains a UTF8 string representing the model n...
Part of the Human Interface Device service.
Not used in a service as a characteristic.
Part of the Human Interface Device service.
Value of a Characteristic Presentation Format descriptor.
Permits writes of the characteristic value with response.
Control point of the Immediate Alert service that allows the client to command the server to alert to...
Characteristic of the Environmental Sensing Service that exposes the pressure measured.
Characteristic of the Device Information Service, which exposes various regulatory or certification c...
Pulse Oxymeter, Glucose and Continuous Glucose Monitoring services use this control point to provide ...
SecurityManager::SecurityMode_t getRequiredSecurity() const
Get the characteristic&#39;s required security.
GattAuthCallbackReply_t
Enumeration of allowed values returned by read or write authorization process.
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.