diff --git a/features/FEATURE_BLE/ble/GattCharacteristic.h b/features/FEATURE_BLE/ble/GattCharacteristic.h index 37d2dd1e74..a8fc818cdd 100644 --- a/features/FEATURE_BLE/ble/GattCharacteristic.h +++ b/features/FEATURE_BLE/ble/GattCharacteristic.h @@ -32,319 +32,1344 @@ * @{ */ +/** + * Representation of a GattServer characteristic. + * + * A characteristic is a typed value enclosed in a GATT service (GattService). + * + * @par Type + * + * The type of the value defines the purpose of the characteristic and is + * represented by a UUID. Standard characteristic types may be consulted at + * https://www.bluetooth.com/specifications/gatt/characteristics . + * + * @par Supported operations + * A set of properties define what client operations are supported by the + * characteristic. See GattServer::Properties_t . + * + * @par Descriptors + * + * Additional information such as the unit of the characteristic value, a + * description string or a client control point can be added to the + * characteristic. + * + * See BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part G] - 3.3.1.1 + * + * One of the most important type of descriptor is the Client Characteristic + * Configuration Descriptor (CCCD) that must be present if the characteristic + * properties allows a client to subscribe to updates of the characteristic + * value. + * + * @par Characteristic breakdown + * + * A characteristic is composed of several GATT attributes (GattAttribute): + * - Characteristic declaration: It contains the properties of the + * characteristic, its type and the handle of its value. + * - Characteristic value: The value of the characteristic. + * - Descriptors: Each descriptor is stored in a single GATT attribute. + * + * When the GattService containing the characteristic is registered in the + * GattServer, a unique attribute handle is assigned to the various attributes + * of the characteristic. This handle is used by clients to interact with the + * characteristic and is used locally in GattServer APIs. + * + * + * + + * + * + * + * + * Representation of a GattServer characteristic. + * + * A characteristic is a typed value used in a service. It contains a set of + * properties which define client operations supported by the characteristic. + * A characteristic may also includes descriptors; a descriptor exposes meta + * information associated to a characteristic such as the unit of its value, its + * human readable name or a control point attribute that allow client to + * subscribe to the characteristic notifications. + * + * The GattCharacteristic class allows application code to construct + * and monitor characteristics presents in a GattServer. + */ class GattCharacteristic { public: + + /* + * Enumeration of characteristic UUID defined by the Bluetooth body. + */ enum { - UUID_BATTERY_LEVEL_STATE_CHAR = 0x2A1B, - UUID_BATTERY_POWER_STATE_CHAR = 0x2A1A, - UUID_REMOVABLE_CHAR = 0x2A3A, - UUID_SERVICE_REQUIRED_CHAR = 0x2A3B, - UUID_ALERT_CATEGORY_ID_CHAR = 0x2A43, - UUID_ALERT_CATEGORY_ID_BIT_MASK_CHAR = 0x2A42, - UUID_ALERT_LEVEL_CHAR = 0x2A06, - UUID_ALERT_NOTIFICATION_CONTROL_POINT_CHAR = 0x2A44, - UUID_ALERT_STATUS_CHAR = 0x2A3F, - UUID_BATTERY_LEVEL_CHAR = 0x2A19, - UUID_BLOOD_PRESSURE_FEATURE_CHAR = 0x2A49, - UUID_BLOOD_PRESSURE_MEASUREMENT_CHAR = 0x2A35, - UUID_BODY_SENSOR_LOCATION_CHAR = 0x2A38, - UUID_BOOT_KEYBOARD_INPUT_REPORT_CHAR = 0x2A22, - UUID_BOOT_KEYBOARD_OUTPUT_REPORT_CHAR = 0x2A32, - UUID_BOOT_MOUSE_INPUT_REPORT_CHAR = 0x2A33, - UUID_CURRENT_TIME_CHAR = 0x2A2B, - UUID_DATE_TIME_CHAR = 0x2A08, - UUID_DAY_DATE_TIME_CHAR = 0x2A0A, - UUID_DAY_OF_WEEK_CHAR = 0x2A09, - UUID_DST_OFFSET_CHAR = 0x2A0D, - UUID_EXACT_TIME_256_CHAR = 0x2A0C, - UUID_FIRMWARE_REVISION_STRING_CHAR = 0x2A26, - UUID_GLUCOSE_FEATURE_CHAR = 0x2A51, - UUID_GLUCOSE_MEASUREMENT_CHAR = 0x2A18, - UUID_GLUCOSE_MEASUREMENT_CONTEXT_CHAR = 0x2A34, - UUID_HARDWARE_REVISION_STRING_CHAR = 0x2A27, - UUID_HEART_RATE_CONTROL_POINT_CHAR = 0x2A39, - UUID_HEART_RATE_MEASUREMENT_CHAR = 0x2A37, - UUID_HID_CONTROL_POINT_CHAR = 0x2A4C, - UUID_HID_INFORMATION_CHAR = 0x2A4A, - UUID_HUMIDITY_CHAR = 0x2A6F, + /** + * Not used in actual BLE service. + */ + UUID_BATTERY_LEVEL_STATE_CHAR = 0x2A1B, + + /** + * Not used in actual BLE service. + */ + UUID_BATTERY_POWER_STATE_CHAR = 0x2A1A, + + /** + * Not used in actual BLE service. + */ + UUID_REMOVABLE_CHAR = 0x2A3A, + + /** + * Not used in actual BLE service. + */ + UUID_SERVICE_REQUIRED_CHAR = 0x2A3B, + + /** + * Not used as a characteristic UUID. + */ + UUID_ALERT_CATEGORY_ID_CHAR = 0x2A43, + + /** + * Not used as a characteristic UUID. + */ + UUID_ALERT_CATEGORY_ID_BIT_MASK_CHAR = 0x2A42, + + /** + * Control point of the Immediate Alert service that allows client to + * command the server to alert to a given level. + */ + UUID_ALERT_LEVEL_CHAR = 0x2A06, + + /** + * Control point of the Alert Notification service that allows client + * finely tune the notification configuration. + */ + UUID_ALERT_NOTIFICATION_CONTROL_POINT_CHAR = 0x2A44, + + /** + * Part of the Alert Notification service which exposes the count of + * unread alert events existing in the server. + */ + UUID_ALERT_STATUS_CHAR = 0x2A3F, + + /** + * Characteristic of the Battery service which exposes the current + * battery level as a percentage. + */ + UUID_BATTERY_LEVEL_CHAR = 0x2A19, + + /** + * Describe the features supported by the blood pressure sensor exposed + * by the Blood Pressure service. + */ + UUID_BLOOD_PRESSURE_FEATURE_CHAR = 0x2A49, + + /** + * Characteristic of the Blood Pressure service that exposes the + * measurement of the blood sensor. + */ + UUID_BLOOD_PRESSURE_MEASUREMENT_CHAR = 0x2A35, + + /** + * Characteristic of the Heart Rate service that indicate the intended + * location of the heart rate monitor. + */ + UUID_BODY_SENSOR_LOCATION_CHAR = 0x2A38, + + /** + * Part of the Human Interface Device service. + */ + UUID_BOOT_KEYBOARD_INPUT_REPORT_CHAR = 0x2A22, + + /** + * Part of the Human Interface Device service. + */ + UUID_BOOT_KEYBOARD_OUTPUT_REPORT_CHAR = 0x2A32, + + /** + * Part of the Human Interface Device service. + */ + UUID_BOOT_MOUSE_INPUT_REPORT_CHAR = 0x2A33, + + /** + * Characteristic of the Current Time service that contains the current + * time. + */ + UUID_CURRENT_TIME_CHAR = 0x2A2B, + + /** + * Not used in a service as a characteristic. + */ + UUID_DATE_TIME_CHAR = 0x2A08, + + /** + * Not used in a service as a characteristic. + */ + UUID_DAY_DATE_TIME_CHAR = 0x2A0A, + + /** + * Not used in a service as a characteristic. + */ + UUID_DAY_OF_WEEK_CHAR = 0x2A09, + + /** + * Not used in a service as a characteristic. + */ + UUID_DST_OFFSET_CHAR = 0x2A0D, + + /** + * Not used in a service as a characteristic. + */ + UUID_EXACT_TIME_256_CHAR = 0x2A0C, + + /** + * Characteristic of the Device Information Service that contains an + * UTF8 string representing the firmware revision for the firmware within + * the device. + */ + UUID_FIRMWARE_REVISION_STRING_CHAR = 0x2A26, + + /** + * Characteristic of the Glucose service that exposes features supported + * by the server. + */ + UUID_GLUCOSE_FEATURE_CHAR = 0x2A51, + + /** + * Characteristic of the Glucose service that exposes glucose + * measurements. + */ + UUID_GLUCOSE_MEASUREMENT_CHAR = 0x2A18, + + /** + * Characteristic of the Glucose service that sends additional + * information related to the glucose measurements. + */ + UUID_GLUCOSE_MEASUREMENT_CONTEXT_CHAR = 0x2A34, + + /** + * Characteristic of the Device Information Service that contains an + * UTF8 string representing the hardware revision of the device. + */ + UUID_HARDWARE_REVISION_STRING_CHAR = 0x2A27, + + /** + * Characteristic of the Heart Rate service used by the client to control + * the service behavior. + */ + UUID_HEART_RATE_CONTROL_POINT_CHAR = 0x2A39, + + /** + * Characteristic of the Heart Rate that send heart rate measurements to + * registered clients. + */ + UUID_HEART_RATE_MEASUREMENT_CHAR = 0x2A37, + + /** + * Part of the Human Interface Device service. + */ + UUID_HID_CONTROL_POINT_CHAR = 0x2A4C, + + /** + * Part of the Human Interface Device service. + */ + UUID_HID_INFORMATION_CHAR = 0x2A4A, + + /** + * Characteristic of the Environmental Sensing service which exposes + * humidity measurements. + */ + UUID_HUMIDITY_CHAR = 0x2A6F, + + /** + * Characteristic of the Device Information Service which exposes + * various regulatory or certification compliance items to which the + * device claims adherence. + */ UUID_IEEE_REGULATORY_CERTIFICATION_DATA_LIST_CHAR = 0x2A2A, - UUID_INTERMEDIATE_CUFF_PRESSURE_CHAR = 0x2A36, - UUID_INTERMEDIATE_TEMPERATURE_CHAR = 0x2A1E, - UUID_LOCAL_TIME_INFORMATION_CHAR = 0x2A0F, - UUID_MANUFACTURER_NAME_STRING_CHAR = 0x2A29, - UUID_MEASUREMENT_INTERVAL_CHAR = 0x2A21, - UUID_MODEL_NUMBER_STRING_CHAR = 0x2A24, - UUID_UNREAD_ALERT_CHAR = 0x2A45, - UUID_NEW_ALERT_CHAR = 0x2A46, - UUID_PNP_ID_CHAR = 0x2A50, - UUID_PRESSURE_CHAR = 0x2A6D, - UUID_PROTOCOL_MODE_CHAR = 0x2A4E, - UUID_RECORD_ACCESS_CONTROL_POINT_CHAR = 0x2A52, - UUID_REFERENCE_TIME_INFORMATION_CHAR = 0x2A14, - UUID_REPORT_CHAR = 0x2A4D, - UUID_REPORT_MAP_CHAR = 0x2A4B, - UUID_RINGER_CONTROL_POINT_CHAR = 0x2A40, - UUID_RINGER_SETTING_CHAR = 0x2A41, - UUID_SCAN_INTERVAL_WINDOW_CHAR = 0x2A4F, - UUID_SCAN_REFRESH_CHAR = 0x2A31, - UUID_SERIAL_NUMBER_STRING_CHAR = 0x2A25, - UUID_SOFTWARE_REVISION_STRING_CHAR = 0x2A28, - UUID_SUPPORTED_NEW_ALERT_CATEGORY_CHAR = 0x2A47, - UUID_SUPPORTED_UNREAD_ALERT_CATEGORY_CHAR = 0x2A48, - UUID_SYSTEM_ID_CHAR = 0x2A23, - UUID_TEMPERATURE_CHAR = 0x2A6E, - UUID_TEMPERATURE_MEASUREMENT_CHAR = 0x2A1C, - UUID_TEMPERATURE_TYPE_CHAR = 0x2A1D, - UUID_TIME_ACCURACY_CHAR = 0x2A12, - UUID_TIME_SOURCE_CHAR = 0x2A13, - UUID_TIME_UPDATE_CONTROL_POINT_CHAR = 0x2A16, - UUID_TIME_UPDATE_STATE_CHAR = 0x2A17, - UUID_TIME_WITH_DST_CHAR = 0x2A11, - UUID_TIME_ZONE_CHAR = 0x2A0E, - UUID_TX_POWER_LEVEL_CHAR = 0x2A07, - UUID_CSC_FEATURE_CHAR = 0x2A5C, - UUID_CSC_MEASUREMENT_CHAR = 0x2A5B, - UUID_RSC_FEATURE_CHAR = 0x2A54, - UUID_RSC_MEASUREMENT_CHAR = 0x2A53 + + /** + * Characteristic of the Blood Pressure service which exposes intermediate + * cuff pressure measurements. + */ + UUID_INTERMEDIATE_CUFF_PRESSURE_CHAR = 0x2A36, + + /** + * Characteristic of the Health Thermometer service that sens intermediate + * temperature values while the measurement is in progress. + */ + UUID_INTERMEDIATE_TEMPERATURE_CHAR = 0x2A1E, + + /** + * Characteristic of the current Time service that exposes information + * about the local time. + */ + UUID_LOCAL_TIME_INFORMATION_CHAR = 0x2A0F, + + /** + * Characteristic of the Device Information Service that contains an + * UTF8 string representing the manufacturer name of the device. + */ + UUID_MANUFACTURER_NAME_STRING_CHAR = 0x2A29, + + /** + * Characteristic of the Health Thermometer service that exposes the + * interval time between two measurements. + */ + UUID_MEASUREMENT_INTERVAL_CHAR = 0x2A21, + + /** + * Characteristic of the Device Information Service that contains an + * UTF8 string representing the model number of the device assigned by + * the vendor. + */ + UUID_MODEL_NUMBER_STRING_CHAR = 0x2A24, + + /** + * Characteristic of the Alert Notification Service that shows how many + * numbers of unread alerts exist in the specific category in the device. + */ + UUID_UNREAD_ALERT_CHAR = 0x2A45, + + /** + * Characteristic of the Alert Notification Service that defines the + * category of the alert and how many new alerts of that category have + * occurred in the server. + */ + UUID_NEW_ALERT_CHAR = 0x2A46, + + /** + * Characteristic of the Device Information Service; it is a set of + * values used to create a device ID that is unique for this device. + */ + UUID_PNP_ID_CHAR = 0x2A50, + + /** + * Characteristic of the Environmental Sensing Service that expose the + * pressure measured. + */ + UUID_PRESSURE_CHAR = 0x2A6D, + + /** + * Part of the Human Interface Device service. + */ + UUID_PROTOCOL_MODE_CHAR = 0x2A4E, + + /** + * This control point is used by Pulse Oxymeter, Glucose and Continuous + * Glucose Monitoring services to provide basic management of the patient + * record database. + */ + UUID_RECORD_ACCESS_CONTROL_POINT_CHAR = 0x2A52, + + /** + * Characteristic of the Current Time service that exposes information + * related to the current time served (accuracy, source, hours since + * update and so on). + */ + UUID_REFERENCE_TIME_INFORMATION_CHAR = 0x2A14, + + /** + * Part of the Human Interface Device service. + */ + UUID_REPORT_CHAR = 0x2A4D, + + /** + * Part of the Human Interface Device service. + */ + UUID_REPORT_MAP_CHAR = 0x2A4B, + + /** + * Characteristic of the Phone Alert Status service that allows a client + * to configure operating mode. + */ + UUID_RINGER_CONTROL_POINT_CHAR = 0x2A40, + + /** + * Characteristic of the Phone Alert Status service that returns the + * ringer setting when read. + */ + UUID_RINGER_SETTING_CHAR = 0x2A41, + + /** + * Characteristic of the Scan Parameter service that store client's + * the scan parameters (scan interval and scan window). + */ + UUID_SCAN_INTERVAL_WINDOW_CHAR = 0x2A4F, + + /** + * Characteristic of the Scan Parameter service that send a notification + * to a client when the server requires its latest scan parameters. + */ + UUID_SCAN_REFRESH_CHAR = 0x2A31, + + /** + * Characteristic of the Device Information Service that contains an + * UTF-8 string representing the serial number of the device. + */ + UUID_SERIAL_NUMBER_STRING_CHAR = 0x2A25, + + /** + * Characteristic of the Device Information Service that contains an + * UTF8 string representing the software revision of the device. + */ + UUID_SOFTWARE_REVISION_STRING_CHAR = 0x2A28, + + /** + * Characteristic of the Alert Notification Service that notify to + * subscribed client the count of new alerts for a given category. + */ + UUID_SUPPORTED_NEW_ALERT_CATEGORY_CHAR = 0x2A47, + + /** + * Characteristic of the Alert Notification service which exposes + * categories of unread alert supported by the server. + */ + UUID_SUPPORTED_UNREAD_ALERT_CATEGORY_CHAR = 0x2A48, + + /** + * Characteristic of the Device Information Service that exposes a + * structure containing an Organizationally Unique Identifier (OUI) + * followed by a manufacturer-defined identifier. The value of the + * structure is unique for each individual instance of the product. + */ + UUID_SYSTEM_ID_CHAR = 0x2A23, + + /** + * Characteristic of the Environmental Sensing service that exposes the + * temperature measurement with a resolution of 0.01 degree Celsius. + */ + UUID_TEMPERATURE_CHAR = 0x2A6E, + + /** + * Characteristic of the Health Thermometer service that sends temperature + * measurement to clients. + */ + UUID_TEMPERATURE_MEASUREMENT_CHAR = 0x2A1C, + + /** + * Characteristic of the Health Thermometer service that describes the + * where the measurement should take place. + */ + UUID_TEMPERATURE_TYPE_CHAR = 0x2A1D, + + /** + * Not used in a service as a characteristic. + */ + UUID_TIME_ACCURACY_CHAR = 0x2A12, + + /** + * Not used in a service as a characteristic. + */ + UUID_TIME_SOURCE_CHAR = 0x2A13, + + /** + * Characteristic of the Reference Time service that allow clients to + * control time update. + */ + UUID_TIME_UPDATE_CONTROL_POINT_CHAR = 0x2A16, + + /** + * Characteristic of the Reference Time service that informs clients of + * the status of the time update operation. + */ + UUID_TIME_UPDATE_STATE_CHAR = 0x2A17, + + /** + * Characteristic of the Next DST Change service that returns to clients + * the time with DST. + */ + UUID_TIME_WITH_DST_CHAR = 0x2A11, + + /** + * Not used in a service as a characteristic. + */ + UUID_TIME_ZONE_CHAR = 0x2A0E, + + /** + * Characteristic of the TX Power service that expose the current + * transmission power in dBm. + */ + UUID_TX_POWER_LEVEL_CHAR = 0x2A07, + + /** + * Characteristic of the Cycling Speed and Cadence (CSC) service that + * exposes features supported by the server. + */ + UUID_CSC_FEATURE_CHAR = 0x2A5C, + + /** + * Characteristic of the Cycling Speed and Cadence (CSC) service that + * exposes measurements made by the server. + */ + UUID_CSC_MEASUREMENT_CHAR = 0x2A5B, + + /** + * Characteristic of the Running Speed and Cadence (RSC) service that + * exposes features supported by the server. + */ + UUID_RSC_FEATURE_CHAR = 0x2A54, + + /** + * Characteristic of the Running Speed and Cadence (RSC) service that + * exposes measurements made by the server. + */ + UUID_RSC_MEASUREMENT_CHAR = 0x2A53 }; /** - * @brief Standard GATT characteristic presentation format unit types. - * These unit types are used to describe what the raw numeric - * data in a characteristic actually represents. + * Unit type of a characteristic value. * - * @note See https://developer.bluetooth.org/gatt/units/Pages/default.aspx + * These unit types are used to describe what the raw numeric data in a + * characteristic actually represents. A server can exposes that information + * to its clients by adding a Characteristic Presentation Format descriptor + * to relevant characteristics. + * + * @note See https://developer.bluetooth.org/gatt/units/Pages/default.aspx */ enum { - BLE_GATT_UNIT_NONE = 0x2700, /**< No specified unit type. */ - BLE_GATT_UNIT_LENGTH_METRE = 0x2701, /**< Length, metre. */ - BLE_GATT_UNIT_MASS_KILOGRAM = 0x2702, /**< Mass, kilogram. */ - BLE_GATT_UNIT_TIME_SECOND = 0x2703, /**< Time, second. */ - BLE_GATT_UNIT_ELECTRIC_CURRENT_AMPERE = 0x2704, /**< Electric current, ampere. */ - BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_KELVIN = 0x2705, /**< Thermodynamic temperature, kelvin. */ - BLE_GATT_UNIT_AMOUNT_OF_SUBSTANCE_MOLE = 0x2706, /**< Amount of substance, mole. */ - BLE_GATT_UNIT_LUMINOUS_INTENSITY_CANDELA = 0x2707, /**< Luminous intensity, candela. */ - BLE_GATT_UNIT_AREA_SQUARE_METRES = 0x2710, /**< Area, square metres. */ - BLE_GATT_UNIT_VOLUME_CUBIC_METRES = 0x2711, /**< Volume, cubic metres. */ - BLE_GATT_UNIT_VELOCITY_METRES_PER_SECOND = 0x2712, /**< Velocity, metres per second. */ - BLE_GATT_UNIT_ACCELERATION_METRES_PER_SECOND_SQUARED = 0x2713, /**< Acceleration, metres per second squared. */ - BLE_GATT_UNIT_WAVENUMBER_RECIPROCAL_METRE = 0x2714, /**< Wave number reciprocal, metre. */ - BLE_GATT_UNIT_DENSITY_KILOGRAM_PER_CUBIC_METRE = 0x2715, /**< Density, kilogram per cubic metre. */ - BLE_GATT_UNIT_SURFACE_DENSITY_KILOGRAM_PER_SQUARE_METRE = 0x2716, /**< */ - BLE_GATT_UNIT_SPECIFIC_VOLUME_CUBIC_METRE_PER_KILOGRAM = 0x2717, /**< */ - BLE_GATT_UNIT_CURRENT_DENSITY_AMPERE_PER_SQUARE_METRE = 0x2718, /**< */ - BLE_GATT_UNIT_MAGNETIC_FIELD_STRENGTH_AMPERE_PER_METRE = 0x2719, /**< Magnetic field strength, ampere per metre. */ - BLE_GATT_UNIT_AMOUNT_CONCENTRATION_MOLE_PER_CUBIC_METRE = 0x271A, /**< */ - BLE_GATT_UNIT_MASS_CONCENTRATION_KILOGRAM_PER_CUBIC_METRE = 0x271B, /**< */ - BLE_GATT_UNIT_LUMINANCE_CANDELA_PER_SQUARE_METRE = 0x271C, /**< */ - BLE_GATT_UNIT_REFRACTIVE_INDEX = 0x271D, /**< */ - BLE_GATT_UNIT_RELATIVE_PERMEABILITY = 0x271E, /**< */ - BLE_GATT_UNIT_PLANE_ANGLE_RADIAN = 0x2720, /**< */ - BLE_GATT_UNIT_SOLID_ANGLE_STERADIAN = 0x2721, /**< */ - BLE_GATT_UNIT_FREQUENCY_HERTZ = 0x2722, /**< Frequency, hertz. */ - BLE_GATT_UNIT_FORCE_NEWTON = 0x2723, /**< Force, newton. */ - BLE_GATT_UNIT_PRESSURE_PASCAL = 0x2724, /**< Pressure, pascal. */ - BLE_GATT_UNIT_ENERGY_JOULE = 0x2725, /**< Energy, joule. */ - BLE_GATT_UNIT_POWER_WATT = 0x2726, /**< Power, watt. */ - BLE_GATT_UNIT_ELECTRIC_CHARGE_COULOMB = 0x2727, /**< Electrical charge, coulomb. */ - BLE_GATT_UNIT_ELECTRIC_POTENTIAL_DIFFERENCE_VOLT = 0x2728, /**< Electrical potential difference, voltage. */ - BLE_GATT_UNIT_CAPACITANCE_FARAD = 0x2729, /**< */ - BLE_GATT_UNIT_ELECTRIC_RESISTANCE_OHM = 0x272A, /**< */ - BLE_GATT_UNIT_ELECTRIC_CONDUCTANCE_SIEMENS = 0x272B, /**< */ - BLE_GATT_UNIT_MAGNETIC_FLEX_WEBER = 0x272C, /**< */ - BLE_GATT_UNIT_MAGNETIC_FLEX_DENSITY_TESLA = 0x272D, /**< */ - BLE_GATT_UNIT_INDUCTANCE_HENRY = 0x272E, /**< */ - BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_CELSIUS = 0x272F, /**< */ - BLE_GATT_UNIT_LUMINOUS_FLUX_LUMEN = 0x2730, /**< */ - BLE_GATT_UNIT_ILLUMINANCE_LUX = 0x2731, /**< */ - BLE_GATT_UNIT_ACTIVITY_REFERRED_TO_A_RADIONUCLIDE_BECQUEREL = 0x2732, /**< */ - BLE_GATT_UNIT_ABSORBED_DOSE_GRAY = 0x2733, /**< */ - BLE_GATT_UNIT_DOSE_EQUIVALENT_SIEVERT = 0x2734, /**< */ - BLE_GATT_UNIT_CATALYTIC_ACTIVITY_KATAL = 0x2735, /**< */ - BLE_GATT_UNIT_DYNAMIC_VISCOSITY_PASCAL_SECOND = 0x2740, /**< */ - BLE_GATT_UNIT_MOMENT_OF_FORCE_NEWTON_METRE = 0x2741, /**< */ - BLE_GATT_UNIT_SURFACE_TENSION_NEWTON_PER_METRE = 0x2742, /**< */ - BLE_GATT_UNIT_ANGULAR_VELOCITY_RADIAN_PER_SECOND = 0x2743, /**< */ - BLE_GATT_UNIT_ANGULAR_ACCELERATION_RADIAN_PER_SECOND_SQUARED = 0x2744, /**< */ - BLE_GATT_UNIT_HEAT_FLUX_DENSITY_WATT_PER_SQUARE_METRE = 0x2745, /**< */ - BLE_GATT_UNIT_HEAT_CAPACITY_JOULE_PER_KELVIN = 0x2746, /**< */ - BLE_GATT_UNIT_SPECIFIC_HEAT_CAPACITY_JOULE_PER_KILOGRAM_KELVIN = 0x2747, /**< */ - BLE_GATT_UNIT_SPECIFIC_ENERGY_JOULE_PER_KILOGRAM = 0x2748, /**< */ - BLE_GATT_UNIT_THERMAL_CONDUCTIVITY_WATT_PER_METRE_KELVIN = 0x2749, /**< */ - BLE_GATT_UNIT_ENERGY_DENSITY_JOULE_PER_CUBIC_METRE = 0x274A, /**< */ - BLE_GATT_UNIT_ELECTRIC_FIELD_STRENGTH_VOLT_PER_METRE = 0x274B, /**< */ - BLE_GATT_UNIT_ELECTRIC_CHARGE_DENSITY_COULOMB_PER_CUBIC_METRE = 0x274C, /**< */ - BLE_GATT_UNIT_SURFACE_CHARGE_DENSITY_COULOMB_PER_SQUARE_METRE = 0x274D, /**< */ - BLE_GATT_UNIT_ELECTRIC_FLUX_DENSITY_COULOMB_PER_SQUARE_METRE = 0x274E, /**< */ - BLE_GATT_UNIT_PERMITTIVITY_FARAD_PER_METRE = 0x274F, /**< */ - BLE_GATT_UNIT_PERMEABILITY_HENRY_PER_METRE = 0x2750, /**< */ - BLE_GATT_UNIT_MOLAR_ENERGY_JOULE_PER_MOLE = 0x2751, /**< */ - BLE_GATT_UNIT_MOLAR_ENTROPY_JOULE_PER_MOLE_KELVIN = 0x2752, /**< */ - BLE_GATT_UNIT_EXPOSURE_COULOMB_PER_KILOGRAM = 0x2753, /**< */ - BLE_GATT_UNIT_ABSORBED_DOSE_RATE_GRAY_PER_SECOND = 0x2754, /**< */ - BLE_GATT_UNIT_RADIANT_INTENSITY_WATT_PER_STERADIAN = 0x2755, /**< */ - BLE_GATT_UNIT_RADIANCE_WATT_PER_SQUARE_METRE_STERADIAN = 0x2756, /**< */ - BLE_GATT_UNIT_CATALYTIC_ACTIVITY_CONCENTRATION_KATAL_PER_CUBIC_METRE = 0x2757, /**< */ - BLE_GATT_UNIT_TIME_MINUTE = 0x2760, /**< Time, minute. */ - BLE_GATT_UNIT_TIME_HOUR = 0x2761, /**< Time, hour. */ - BLE_GATT_UNIT_TIME_DAY = 0x2762, /**< Time, day. */ - BLE_GATT_UNIT_PLANE_ANGLE_DEGREE = 0x2763, /**< */ - BLE_GATT_UNIT_PLANE_ANGLE_MINUTE = 0x2764, /**< */ - BLE_GATT_UNIT_PLANE_ANGLE_SECOND = 0x2765, /**< */ - BLE_GATT_UNIT_AREA_HECTARE = 0x2766, /**< */ - BLE_GATT_UNIT_VOLUME_LITRE = 0x2767, /**< */ - BLE_GATT_UNIT_MASS_TONNE = 0x2768, /**< */ - BLE_GATT_UNIT_PRESSURE_BAR = 0x2780, /**< Pressure, bar. */ - BLE_GATT_UNIT_PRESSURE_MILLIMETRE_OF_MERCURY = 0x2781, /**< Pressure, millimetre of mercury. */ - BLE_GATT_UNIT_LENGTH_ANGSTROM = 0x2782, /**< */ - BLE_GATT_UNIT_LENGTH_NAUTICAL_MILE = 0x2783, /**< */ - BLE_GATT_UNIT_AREA_BARN = 0x2784, /**< */ - BLE_GATT_UNIT_VELOCITY_KNOT = 0x2785, /**< */ - BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_NEPER = 0x2786, /**< */ - BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_BEL = 0x2787, /**< */ - BLE_GATT_UNIT_LENGTH_YARD = 0x27A0, /**< Length, yard. */ - BLE_GATT_UNIT_LENGTH_PARSEC = 0x27A1, /**< Length, parsec. */ - BLE_GATT_UNIT_LENGTH_INCH = 0x27A2, /**< Length, inch. */ - BLE_GATT_UNIT_LENGTH_FOOT = 0x27A3, /**< Length, foot. */ - BLE_GATT_UNIT_LENGTH_MILE = 0x27A4, /**< Length, mile. */ - BLE_GATT_UNIT_PRESSURE_POUND_FORCE_PER_SQUARE_INCH = 0x27A5, /**< */ - BLE_GATT_UNIT_VELOCITY_KILOMETRE_PER_HOUR = 0x27A6, /**< Velocity, kilometre per hour. */ - BLE_GATT_UNIT_VELOCITY_MILE_PER_HOUR = 0x27A7, /**< Velocity, mile per hour. */ - BLE_GATT_UNIT_ANGULAR_VELOCITY_REVOLUTION_PER_MINUTE = 0x27A8, /**< Angular Velocity, revolution per minute. */ - BLE_GATT_UNIT_ENERGY_GRAM_CALORIE = 0x27A9, /**< Energy, gram calorie. */ - BLE_GATT_UNIT_ENERGY_KILOGRAM_CALORIE = 0x27AA, /**< Energy, kilogram calorie. */ - BLE_GATT_UNIT_ENERGY_KILOWATT_HOUR = 0x27AB, /**< Energy, killowatt hour. */ - BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_FAHRENHEIT = 0x27AC, /**< */ - BLE_GATT_UNIT_PERCENTAGE = 0x27AD, /**< Percentage. */ - BLE_GATT_UNIT_PER_MILLE = 0x27AE, /**< */ - BLE_GATT_UNIT_PERIOD_BEATS_PER_MINUTE = 0x27AF, /**< */ - BLE_GATT_UNIT_ELECTRIC_CHARGE_AMPERE_HOURS = 0x27B0, /**< */ - BLE_GATT_UNIT_MASS_DENSITY_MILLIGRAM_PER_DECILITRE = 0x27B1, /**< */ - BLE_GATT_UNIT_MASS_DENSITY_MILLIMOLE_PER_LITRE = 0x27B2, /**< */ - BLE_GATT_UNIT_TIME_YEAR = 0x27B3, /**< Time, year. */ - BLE_GATT_UNIT_TIME_MONTH = 0x27B4, /**< Time, month. */ - BLE_GATT_UNIT_CONCENTRATION_COUNT_PER_CUBIC_METRE = 0x27B5, /**< */ - BLE_GATT_UNIT_IRRADIANCE_WATT_PER_SQUARE_METRE = 0x27B6 /**< */ + + /** + * No specified unit type. + */ + BLE_GATT_UNIT_NONE = 0x2700, + + /** + * Length, metre. + */ + BLE_GATT_UNIT_LENGTH_METRE = 0x2701, + + /** + * Mass, kilogram. + */ + BLE_GATT_UNIT_MASS_KILOGRAM = 0x2702, + + /** + * Time, second. + */ + BLE_GATT_UNIT_TIME_SECOND = 0x2703, + + /** + * Electric current, ampere. + */ + BLE_GATT_UNIT_ELECTRIC_CURRENT_AMPERE = 0x2704, + + /** + * Thermodynamic temperature, kelvin. + */ + BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_KELVIN = 0x2705, + + /** Amount of substance, mole. + * + */ + BLE_GATT_UNIT_AMOUNT_OF_SUBSTANCE_MOLE = 0x2706, + + /** + * Luminous intensity, candela. + */ + BLE_GATT_UNIT_LUMINOUS_INTENSITY_CANDELA = 0x2707, + + /** + * Area, square metres. + */ + BLE_GATT_UNIT_AREA_SQUARE_METRES = 0x2710, + + /** + * Volume, cubic metres. + */ + BLE_GATT_UNIT_VOLUME_CUBIC_METRES = 0x2711, + + /** + * Velocity, metres per second. + */ + BLE_GATT_UNIT_VELOCITY_METRES_PER_SECOND = 0x2712, + + /** + * Acceleration, metres per second squared. + */ + BLE_GATT_UNIT_ACCELERATION_METRES_PER_SECOND_SQUARED = 0x2713, + + /** + * Wave number reciprocal, metre. + */ + BLE_GATT_UNIT_WAVENUMBER_RECIPROCAL_METRE = 0x2714, + + /** + * Density, kilogram per cubic metre. + */ + BLE_GATT_UNIT_DENSITY_KILOGRAM_PER_CUBIC_METRE = 0x2715, + + /** + * Surface density (kilogram per square metre). + */ + BLE_GATT_UNIT_SURFACE_DENSITY_KILOGRAM_PER_SQUARE_METRE = 0x2716, + + /** + * Specific volume (cubic metre per kilogram). + */ + BLE_GATT_UNIT_SPECIFIC_VOLUME_CUBIC_METRE_PER_KILOGRAM = 0x2717, + + /** + * Current density (ampere per square metre). + */ + BLE_GATT_UNIT_CURRENT_DENSITY_AMPERE_PER_SQUARE_METRE = 0x2718, + + /** + * Magnetic field strength, ampere per metre. + */ + BLE_GATT_UNIT_MAGNETIC_FIELD_STRENGTH_AMPERE_PER_METRE = 0x2719, + + /** + * Amount concentration (mole per cubic metre). + */ + BLE_GATT_UNIT_AMOUNT_CONCENTRATION_MOLE_PER_CUBIC_METRE = 0x271A, + + /** + * Mass concentration (kilogram per cubic metre). + */ + BLE_GATT_UNIT_MASS_CONCENTRATION_KILOGRAM_PER_CUBIC_METRE = 0x271B, + + /** + * Luminance (candela per square metre). + */ + BLE_GATT_UNIT_LUMINANCE_CANDELA_PER_SQUARE_METRE = 0x271C, + + /** + * Refractive index. + */ + BLE_GATT_UNIT_REFRACTIVE_INDEX = 0x271D, + + /** + * Relative permeability. + */ + BLE_GATT_UNIT_RELATIVE_PERMEABILITY = 0x271E, + + /** + * Plane angle (radian). + */ + BLE_GATT_UNIT_PLANE_ANGLE_RADIAN = 0x2720, + + /** + * Solid angle (steradian). + */ + BLE_GATT_UNIT_SOLID_ANGLE_STERADIAN = 0x2721, + + /** + * Frequency, hertz. + */ + BLE_GATT_UNIT_FREQUENCY_HERTZ = 0x2722, + + /** + * Force, newton. + */ + BLE_GATT_UNIT_FORCE_NEWTON = 0x2723, + + /** + * Pressure, pascal. + */ + BLE_GATT_UNIT_PRESSURE_PASCAL = 0x2724, + + /** + * Energy, joule. + */ + BLE_GATT_UNIT_ENERGY_JOULE = 0x2725, + + /** + * Power, watt. + */ + BLE_GATT_UNIT_POWER_WATT = 0x2726, + + /** + * Electrical charge, coulomb. + */ + BLE_GATT_UNIT_ELECTRIC_CHARGE_COULOMB = 0x2727, + + /** + * Electrical potential difference, voltage. + */ + BLE_GATT_UNIT_ELECTRIC_POTENTIAL_DIFFERENCE_VOLT = 0x2728, + + /** + * Capacitance (farad). + */ + BLE_GATT_UNIT_CAPACITANCE_FARAD = 0x2729, + + /** + * Electric resistance (ohm). + */ + BLE_GATT_UNIT_ELECTRIC_RESISTANCE_OHM = 0x272A, + + /** + * Electric conductance (siemens). + */ + BLE_GATT_UNIT_ELECTRIC_CONDUCTANCE_SIEMENS = 0x272B, + + /** + * Magnetic flux (weber). + */ + BLE_GATT_UNIT_MAGNETIC_FLEX_WEBER = 0x272C, + + /** + * Magnetic flux density (tesla). + */ + BLE_GATT_UNIT_MAGNETIC_FLEX_DENSITY_TESLA = 0x272D, + + /** + * Inductance (henry). + */ + BLE_GATT_UNIT_INDUCTANCE_HENRY = 0x272E, + + /** + * Celsius temperature (degree Celsius). + */ + BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_CELSIUS = 0x272F, + + /** + * Luminous flux (lumen). + */ + BLE_GATT_UNIT_LUMINOUS_FLUX_LUMEN = 0x2730, + + /** + * Illuminance (lux). + */ + BLE_GATT_UNIT_ILLUMINANCE_LUX = 0x2731, + + /** + * Activity referred to a radionuclide (becquerel). + */ + BLE_GATT_UNIT_ACTIVITY_REFERRED_TO_A_RADIONUCLIDE_BECQUEREL = 0x2732, + + /** + * Absorbed dose (gray). + */ + BLE_GATT_UNIT_ABSORBED_DOSE_GRAY = 0x2733, + + /** + * Dose equivalent (sievert). + */ + BLE_GATT_UNIT_DOSE_EQUIVALENT_SIEVERT = 0x2734, + + /** + * Catalytic activity (katal). + */ + BLE_GATT_UNIT_CATALYTIC_ACTIVITY_KATAL = 0x2735, + + /** + * Dynamic viscosity (pascal second). + */ + BLE_GATT_UNIT_DYNAMIC_VISCOSITY_PASCAL_SECOND = 0x2740, + + /** + * Moment of force (newton metre). + */ + BLE_GATT_UNIT_MOMENT_OF_FORCE_NEWTON_METRE = 0x2741, + + /** + * Surface tension (newton per metre). + */ + BLE_GATT_UNIT_SURFACE_TENSION_NEWTON_PER_METRE = 0x2742, + + /** + * Angular velocity (radian per second). + */ + BLE_GATT_UNIT_ANGULAR_VELOCITY_RADIAN_PER_SECOND = 0x2743, + + /** + * Angular acceleration (radian per second squared). + */ + BLE_GATT_UNIT_ANGULAR_ACCELERATION_RADIAN_PER_SECOND_SQUARED = 0x2744, + + /** + * Heat flux density (watt per square metre). + */ + BLE_GATT_UNIT_HEAT_FLUX_DENSITY_WATT_PER_SQUARE_METRE = 0x2745, + + /** + * Heat capacity (joule per kelvin). + */ + BLE_GATT_UNIT_HEAT_CAPACITY_JOULE_PER_KELVIN = 0x2746, + + /** + * Specific heat capacity (joule per kilogram kelvin). + */ + BLE_GATT_UNIT_SPECIFIC_HEAT_CAPACITY_JOULE_PER_KILOGRAM_KELVIN = 0x2747, + + /** + * Specific energy (joule per kilogram). + */ + BLE_GATT_UNIT_SPECIFIC_ENERGY_JOULE_PER_KILOGRAM = 0x2748, + + /** + * Thermal conductivity (watt per metre kelvin). + */ + BLE_GATT_UNIT_THERMAL_CONDUCTIVITY_WATT_PER_METRE_KELVIN = 0x2749, + + /** + * Energy density (joule per cubic metre). + */ + BLE_GATT_UNIT_ENERGY_DENSITY_JOULE_PER_CUBIC_METRE = 0x274A, + + /** + * Electric field strength (volt per metre). + */ + BLE_GATT_UNIT_ELECTRIC_FIELD_STRENGTH_VOLT_PER_METRE = 0x274B, + + /** + * Electric charge density (coulomb per cubic metre). + */ + BLE_GATT_UNIT_ELECTRIC_CHARGE_DENSITY_COULOMB_PER_CUBIC_METRE = 0x274C, + + /** + * Surface charge density (coulomb per square metre). + */ + BLE_GATT_UNIT_SURFACE_CHARGE_DENSITY_COULOMB_PER_SQUARE_METRE = 0x274D, + + /** + * Electric flux density (coulomb per square metre). + */ + BLE_GATT_UNIT_ELECTRIC_FLUX_DENSITY_COULOMB_PER_SQUARE_METRE = 0x274E, + + /** + * Permittivity (farad per metre). + */ + BLE_GATT_UNIT_PERMITTIVITY_FARAD_PER_METRE = 0x274F, + + /** + * Permeability (henry per metre). + */ + BLE_GATT_UNIT_PERMEABILITY_HENRY_PER_METRE = 0x2750, + + /** + * Molar energy (joule per mole). + */ + BLE_GATT_UNIT_MOLAR_ENERGY_JOULE_PER_MOLE = 0x2751, + + /** + * Molar entropy (joule per mole kelvin). + */ + BLE_GATT_UNIT_MOLAR_ENTROPY_JOULE_PER_MOLE_KELVIN = 0x2752, + + /** + * Exposure (coulomb per kilogram). + */ + BLE_GATT_UNIT_EXPOSURE_COULOMB_PER_KILOGRAM = 0x2753, + + /** + * Absorbed dose rate (gray per second). + */ + BLE_GATT_UNIT_ABSORBED_DOSE_RATE_GRAY_PER_SECOND = 0x2754, + + /** + * Radiant intensity (watt per steradian). + */ + BLE_GATT_UNIT_RADIANT_INTENSITY_WATT_PER_STERADIAN = 0x2755, + + /** + * Radiance (watt per square metre steradian). + */ + BLE_GATT_UNIT_RADIANCE_WATT_PER_SQUARE_METRE_STERADIAN = 0x2756, + + /** + * Catalytic activity concentration (katal per cubic metre). + */ + BLE_GATT_UNIT_CATALYTIC_ACTIVITY_CONCENTRATION_KATAL_PER_CUBIC_METRE = 0x2757, + + /** + * Time, minute. + */ + BLE_GATT_UNIT_TIME_MINUTE = 0x2760, + + /** + * Time, hour. + */ + BLE_GATT_UNIT_TIME_HOUR = 0x2761, + + /** + * Time, day. + */ + BLE_GATT_UNIT_TIME_DAY = 0x2762, + + /** + * Plane angle (degree). + */ + BLE_GATT_UNIT_PLANE_ANGLE_DEGREE = 0x2763, + + /** + * Plane angle (minute). + */ + BLE_GATT_UNIT_PLANE_ANGLE_MINUTE = 0x2764, + + /** + * Plane angle (seconds). + */ + BLE_GATT_UNIT_PLANE_ANGLE_SECOND = 0x2765, + + /** + * Area (hectare). + */ + BLE_GATT_UNIT_AREA_HECTARE = 0x2766, + + /** + * Volume (litre). + */ + BLE_GATT_UNIT_VOLUME_LITRE = 0x2767, + + /** + * Mass (tonne). + */ + BLE_GATT_UNIT_MASS_TONNE = 0x2768, + + /** + * Pressure, bar. + */ + BLE_GATT_UNIT_PRESSURE_BAR = 0x2780, + + /** + * Pressure, millimetre of mercury. + */ + BLE_GATT_UNIT_PRESSURE_MILLIMETRE_OF_MERCURY = 0x2781, + + /** + * Length (ngstrm). + */ + BLE_GATT_UNIT_LENGTH_ANGSTROM = 0x2782, + + /** + * Length (nautical mile). + */ + BLE_GATT_UNIT_LENGTH_NAUTICAL_MILE = 0x2783, + + /** + * Area (barn). + */ + BLE_GATT_UNIT_AREA_BARN = 0x2784, + + /** + * Velocity (knot). + */ + BLE_GATT_UNIT_VELOCITY_KNOT = 0x2785, + + /** + * Logarithmic radio quantity (neper). + */ + BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_NEPER = 0x2786, + + /** + * Logarithmic radio quantity (bel). + */ + BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_BEL = 0x2787, + + /** + * Length, yard. + */ + BLE_GATT_UNIT_LENGTH_YARD = 0x27A0, + + /** + * Length, parsec. + */ + BLE_GATT_UNIT_LENGTH_PARSEC = 0x27A1, + + /** + * Length, inch. + */ + BLE_GATT_UNIT_LENGTH_INCH = 0x27A2, + + /** + * Length, foot. + */ + BLE_GATT_UNIT_LENGTH_FOOT = 0x27A3, + + /** + * Length, mile. + */ + BLE_GATT_UNIT_LENGTH_MILE = 0x27A4, + + /** + * Pressure (pound-force per square inch). + */ + BLE_GATT_UNIT_PRESSURE_POUND_FORCE_PER_SQUARE_INCH = 0x27A5, + + /** + * Velocity, kilometre per hour. + */ + BLE_GATT_UNIT_VELOCITY_KILOMETRE_PER_HOUR = 0x27A6, + + /** Velocity, mile per hour. + * + */ + BLE_GATT_UNIT_VELOCITY_MILE_PER_HOUR = 0x27A7, + + /** + * Angular Velocity, revolution per minute. + */ + BLE_GATT_UNIT_ANGULAR_VELOCITY_REVOLUTION_PER_MINUTE = 0x27A8, + + /** + * Energy, gram calorie. + */ + BLE_GATT_UNIT_ENERGY_GRAM_CALORIE = 0x27A9, + + /** + * Energy, kilogram calorie. + */ + BLE_GATT_UNIT_ENERGY_KILOGRAM_CALORIE = 0x27AA, + + /** + * Energy, killowatt hour. + */ + BLE_GATT_UNIT_ENERGY_KILOWATT_HOUR = 0x27AB, + + /** + * Thermodynamic temperature (degree Fahrenheit). + */ + BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_FAHRENHEIT = 0x27AC, + + /** + * Percentage. + */ + BLE_GATT_UNIT_PERCENTAGE = 0x27AD, + + /** + * Per mille. + */ + BLE_GATT_UNIT_PER_MILLE = 0x27AE, + + /** + * Period (beats per minute) + */ + BLE_GATT_UNIT_PERIOD_BEATS_PER_MINUTE = 0x27AF, + + /** + * Electric charge (ampere hours) + */ + BLE_GATT_UNIT_ELECTRIC_CHARGE_AMPERE_HOURS = 0x27B0, + + /** + * Mass density (milligram per decilitre). + */ + BLE_GATT_UNIT_MASS_DENSITY_MILLIGRAM_PER_DECILITRE = 0x27B1, + + /** + * Mass density (millimole per litre). + */ + BLE_GATT_UNIT_MASS_DENSITY_MILLIMOLE_PER_LITRE = 0x27B2, + + /** + * Time, year. + */ + BLE_GATT_UNIT_TIME_YEAR = 0x27B3, + + /** + * Time, month. + */ + BLE_GATT_UNIT_TIME_MONTH = 0x27B4, + + /** + * Concentration (count per cubic metre). + */ + BLE_GATT_UNIT_CONCENTRATION_COUNT_PER_CUBIC_METRE = 0x27B5, + + /** + * Irradiance (watt per square metre). + */ + BLE_GATT_UNIT_IRRADIANCE_WATT_PER_SQUARE_METRE = 0x27B6 }; /** - * @brief Standard GATT number types. + * Presentation format of a characteristic. * - * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2. + * It determines how the value of a characteristic is formatted. A server + * can exposes that information to its clients by adding a Characteristic + * Presentation Format descriptor to relevant characteristics. * - * @note See http://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml + * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2. */ enum { - BLE_GATT_FORMAT_RFU = 0x00, /**< Reserved for future use. */ - BLE_GATT_FORMAT_BOOLEAN = 0x01, /**< Boolean. */ - BLE_GATT_FORMAT_2BIT = 0x02, /**< Unsigned 2-bit integer. */ - BLE_GATT_FORMAT_NIBBLE = 0x03, /**< Unsigned 4-bit integer. */ - BLE_GATT_FORMAT_UINT8 = 0x04, /**< Unsigned 8-bit integer. */ - BLE_GATT_FORMAT_UINT12 = 0x05, /**< Unsigned 12-bit integer. */ - BLE_GATT_FORMAT_UINT16 = 0x06, /**< Unsigned 16-bit integer. */ - BLE_GATT_FORMAT_UINT24 = 0x07, /**< Unsigned 24-bit integer. */ - BLE_GATT_FORMAT_UINT32 = 0x08, /**< Unsigned 32-bit integer. */ - BLE_GATT_FORMAT_UINT48 = 0x09, /**< Unsigned 48-bit integer. */ - BLE_GATT_FORMAT_UINT64 = 0x0A, /**< Unsigned 64-bit integer. */ - BLE_GATT_FORMAT_UINT128 = 0x0B, /**< Unsigned 128-bit integer. */ - BLE_GATT_FORMAT_SINT8 = 0x0C, /**< Signed 2-bit integer. */ - BLE_GATT_FORMAT_SINT12 = 0x0D, /**< Signed 12-bit integer. */ - BLE_GATT_FORMAT_SINT16 = 0x0E, /**< Signed 16-bit integer. */ - BLE_GATT_FORMAT_SINT24 = 0x0F, /**< Signed 24-bit integer. */ - BLE_GATT_FORMAT_SINT32 = 0x10, /**< Signed 32-bit integer. */ - BLE_GATT_FORMAT_SINT48 = 0x11, /**< Signed 48-bit integer. */ - BLE_GATT_FORMAT_SINT64 = 0x12, /**< Signed 64-bit integer. */ - BLE_GATT_FORMAT_SINT128 = 0x13, /**< Signed 128-bit integer. */ - BLE_GATT_FORMAT_FLOAT32 = 0x14, /**< IEEE-754 32-bit floating point. */ - BLE_GATT_FORMAT_FLOAT64 = 0x15, /**< IEEE-754 64-bit floating point. */ - BLE_GATT_FORMAT_SFLOAT = 0x16, /**< IEEE-11073 16-bit SFLOAT. */ - BLE_GATT_FORMAT_FLOAT = 0x17, /**< IEEE-11073 32-bit FLOAT. */ - BLE_GATT_FORMAT_DUINT16 = 0x18, /**< IEEE-20601 format. */ - BLE_GATT_FORMAT_UTF8S = 0x19, /**< UTF-8 string. */ - BLE_GATT_FORMAT_UTF16S = 0x1A, /**< UTF-16 string. */ - BLE_GATT_FORMAT_STRUCT = 0x1B /**< Opaque Structure. */ + /** + * Reserved for future use. + */ + BLE_GATT_FORMAT_RFU = 0x00, + + /** + * Boolean. + */ + BLE_GATT_FORMAT_BOOLEAN = 0x01, + + /** + * Unsigned 2-bit integer. + */ + BLE_GATT_FORMAT_2BIT = 0x02, + + /** + * Unsigned 4-bit integer. + */ + BLE_GATT_FORMAT_NIBBLE = 0x03, + + /** + * Unsigned 8-bit integer. + */ + BLE_GATT_FORMAT_UINT8 = 0x04, + + /** + * Unsigned 12-bit integer. + */ + BLE_GATT_FORMAT_UINT12 = 0x05, + + /** + * Unsigned 16-bit integer. + */ + BLE_GATT_FORMAT_UINT16 = 0x06, + + /** + * Unsigned 24-bit integer. + */ + BLE_GATT_FORMAT_UINT24 = 0x07, + + /** + * Unsigned 32-bit integer. + */ + BLE_GATT_FORMAT_UINT32 = 0x08, + + /** + * Unsigned 48-bit integer. + */ + BLE_GATT_FORMAT_UINT48 = 0x09, + + /** + * Unsigned 64-bit integer. + */ + BLE_GATT_FORMAT_UINT64 = 0x0A, + + /** + * Unsigned 128-bit integer. + */ + BLE_GATT_FORMAT_UINT128 = 0x0B, + + /** + * Signed 8-bit integer. + */ + BLE_GATT_FORMAT_SINT8 = 0x0C, + + /** + * Signed 12-bit integer. + */ + BLE_GATT_FORMAT_SINT12 = 0x0D, + + /** + * Signed 16-bit integer. + */ + BLE_GATT_FORMAT_SINT16 = 0x0E, + + /** + * Signed 24-bit integer. + */ + BLE_GATT_FORMAT_SINT24 = 0x0F, + + /** + * Signed 32-bit integer. + */ + BLE_GATT_FORMAT_SINT32 = 0x10, + + /** + * Signed 48-bit integer. + */ + BLE_GATT_FORMAT_SINT48 = 0x11, + + /** + * Signed 64-bit integer. + */ + BLE_GATT_FORMAT_SINT64 = 0x12, + + /** + * Signed 128-bit integer. + */ + BLE_GATT_FORMAT_SINT128 = 0x13, + + /** + * IEEE-754 32-bit floating point. + */ + BLE_GATT_FORMAT_FLOAT32 = 0x14, + + /** + * IEEE-754 64-bit floating point. + */ + BLE_GATT_FORMAT_FLOAT64 = 0x15, + + /** + * IEEE-11073 16-bit SFLOAT. + */ + BLE_GATT_FORMAT_SFLOAT = 0x16, + + /** + * IEEE-11073 32-bit FLOAT. + */ + BLE_GATT_FORMAT_FLOAT = 0x17, + + /** + * IEEE-20601 format. + */ + BLE_GATT_FORMAT_DUINT16 = 0x18, + + /** + * UTF-8 string. + */ + BLE_GATT_FORMAT_UTF8S = 0x19, + + /** + * UTF-16 string. + */ + BLE_GATT_FORMAT_UTF16S = 0x1A, + + /** + * Opaque Structure. + */ + BLE_GATT_FORMAT_STRUCT = 0x1B }; /*! - * @brief Standard GATT characteristic properties. + * Characteristic properties. * - * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.1.1 - * and Section 3.3.3.1 for Extended Properties. + * It is a bitfield that determines how a characteristic value can be used. + * + * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.1.1 + * and Section 3.3.3.1 for Extended Properties. */ enum Properties_t { - BLE_GATT_CHAR_PROPERTIES_NONE = 0x00, - BLE_GATT_CHAR_PROPERTIES_BROADCAST = 0x01, /**< Permits broadcasts of the characteristic value using the Server Characteristic Configuration descriptor. */ - BLE_GATT_CHAR_PROPERTIES_READ = 0x02, /**< Permits reads of the characteristic value. */ - BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE = 0x04, /**< Permits writes of the characteristic value without response. */ - BLE_GATT_CHAR_PROPERTIES_WRITE = 0x08, /**< Permits writes of the characteristic value with response. */ - BLE_GATT_CHAR_PROPERTIES_NOTIFY = 0x10, /**< Permits notifications of a characteristic value without acknowledgment. */ - BLE_GATT_CHAR_PROPERTIES_INDICATE = 0x20, /**< Permits indications of a characteristic value with acknowledgment. */ - BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES = 0x40, /**< Permits signed writes to the characteristic value. */ - BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES = 0x80 /**< Additional characteristic properties are defined in the Characteristic Extended Properties descriptor */ + /** + * No property defined. + */ + BLE_GATT_CHAR_PROPERTIES_NONE = 0x00, + + /** + * Permits broadcasts of the characteristic value using the Server + * Characteristic Configuration descriptor. + */ + BLE_GATT_CHAR_PROPERTIES_BROADCAST = 0x01, + + /** + * Permits reads of the characteristic value. + */ + BLE_GATT_CHAR_PROPERTIES_READ = 0x02, + + /** + * Permits writes of the characteristic value without response. + */ + BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE = 0x04, + + /** + * Permits writes of the characteristic value with response. + */ + BLE_GATT_CHAR_PROPERTIES_WRITE = 0x08, + + /** + * Permits notifications of a characteristic value without acknowledgment. + */ + BLE_GATT_CHAR_PROPERTIES_NOTIFY = 0x10, + + /** + * Permits indications of a characteristic value with acknowledgment. + */ + BLE_GATT_CHAR_PROPERTIES_INDICATE = 0x20, + + /** + * Permits signed writes to the characteristic value. + */ + BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES = 0x40, + + /** + * Additional characteristic properties are defined in the Characteristic + * Extended Properties descriptor + */ + BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES = 0x80 + }; /** - * @brief GATT presentation format wrapper. + * Value of a Characteristic Presentation Format descriptor. * - * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5. + * Characteristic Presentation Format descriptor express the format of a + * characteristic value. * - * @note See https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml + * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5. */ struct PresentationFormat_t { - uint8_t gatt_format; /**< Format of the value. */ - int8_t exponent; /**< Exponent for integer data types. Example: if Exponent = -3 and the char value is 3892, the actual value is 3.892 */ - uint16_t gatt_unit; /**< UUID from Bluetooth Assigned Numbers. */ - uint8_t gatt_namespace; /**< Namespace from Bluetooth Assigned Numbers, normally '1'. */ - uint16_t gatt_nsdesc; /**< Namespace description from Bluetooth Assigned Numbers, normally '0'. */ + /** + * Format of the value. + */ + uint8_t gatt_format; + + /** + * Exponent for integer data types. + * + * Example: if Exponent = -3 and the char value is 3892, the actual + * value is 3.892 + */ + int8_t exponent; + + /** + * Unit of the characteristic value. + * + * It is an UUID from Bluetooth Assigned Numbers. + */ + uint16_t gatt_unit; + + /** + * Namespace of the description field. + * + * This field identifies the organization that is responsible for + * defining the enumerations for the description field. + * + * The namespace of the Bluetooth Body is 0x01. + */ + uint8_t gatt_namespace; + + /** + * Description. + * + * @note The value 0x0000 means unknown in the Bluetooth namespace. + */ + uint16_t gatt_nsdesc; + }; /** - * @brief Creates a new GattCharacteristic using the specified 16-bit - * UUID, value length and properties. + * @brief Constructs a new GattCharacteristic. * - * @param[in] uuid - * The UUID to use for this characteristic. - * @param[in] valuePtr - * The memory holding the initial value. The value is copied - * into the stack when the enclosing service is added, and - * the stack thereafter maintained it internally. - * @param[in] len - * The length in bytes of this characteristic's value. - * @param[in] maxLen - * The max length in bytes of this characteristic's value. - * @param[in] props - * The 8-bit field containing the characteristic's properties. - * @param[in] descriptors - * A pointer to an array of descriptors to be included within - * this characteristic. The caller owns the memory for the descriptor - * array, which remains valid at least until - * the enclosing service is added to the GATT table. - * @param[in] numDescriptors - * The number of descriptors in the previous array. - * @param[in] hasVariableLen - * Whether the attribute's value length changes over time. + * @param[in] uuid The UUID of this characteristic. + * @param[in] valuePtr Memory buffer holding the initial value. The value is + * copied into the Bluetooth subsytem when the enclosing service is added. + * Thereafter the stack maintains it internally. + * @param[in] len The length in bytes of this characteristic's value. + * @param[in] maxLen The capacity in bytes of the characteristic value + * buffer. + * @param[in] props An 8-bit field that contains the characteristic's + * properties. + * @param[in] descriptors A pointer to an array of descriptors to be included + * within this characteristic. The caller owns the memory for the descriptor + * array, which must remains valid at least until the enclosing service is + * added to the GATT table. + * @param[in] numDescriptors The number of descriptors presents in @p + * descriptors array. + * @param[in] hasVariableLen Flag that indicates if the attribute's value + * length can change over time. * - * @note The UUID value must be unique in the service and is normally >1. + * @note If valuePtr is NULL, length is equal to 0, and the characteristic + * is readable then that particular characteristic may be considered + * optional and dropped while instantiating the service with the underlying + * BLE stack. * - * @note If valuePtr == NULL, length == 0, and properties == READ - * for the value attribute of a characteristic, then that particular - * characteristic may be considered optional and dropped while - * instantiating the service with the underlying BLE stack. + * @note A Client Characteristic Configuration Descriptor (CCCD) should not + * be allocated if either the notify or indicate flag in the @p props bit + * field; the underlying BLE stack handles it. * - * @note A CCCD should not be allocated if either the notify or indicate - * flag is set because the underlying BLE stack handles it. In such - * a case, the param descriptors could be empty and the param - * numDescriptors equal to zero. + * @important GattCharacteristic registered in a GattServer must remain + * valid for the lifetime of the GattServer. */ - 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) : - _valueAttribute(uuid, valuePtr, len, maxLen, hasVariableLen), + 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 + ) : _valueAttribute(uuid, valuePtr, len, maxLen, hasVariableLen), _properties(props), _requiredSecurity(SecurityManager::SECURITY_MODE_ENCRYPTION_OPEN_LINK), _descriptors(descriptors), @@ -353,7 +1378,6 @@ public: enabledWriteAuthorization(false), readAuthorizationCallback(), writeAuthorizationCallback() { - /* empty */ } public: @@ -361,126 +1385,147 @@ public: * Set up the minimum security (mode and level) requirements for access to * the characteristic's value attribute. * - * @param[in] securityMode - * Can be one of encryption or signing, with or without - * protection for man in the middle attacks (MITM). + * @param[in] securityMode Can be one of encryption or signing, with or + * without protection for man in the middle attacks (MITM). */ - void requireSecurity(SecurityManager::SecurityMode_t securityMode) { + void requireSecurity(SecurityManager::SecurityMode_t securityMode) + { _requiredSecurity = securityMode; } public: /** - * Set up callback that will be triggered before the GATT Client is allowed - * to write this characteristic. The handler determines the - * authorization reply for the write. + * Register a callback handling client's write requests or commands. * - * @param[in] callback - * Event handler being registered. + * The callback registered will be invoked when client attempts to write the + * characteristic value; the event handler can accept or reject the write + * request with the appropriate error code. + * + * @param[in] callback Event handler being registered. */ - void setWriteAuthorizationCallback(void (*callback)(GattWriteAuthCallbackParams *)) { + void setWriteAuthorizationCallback( + void (*callback)(GattWriteAuthCallbackParams *) + ) { writeAuthorizationCallback.attach(callback); enabledWriteAuthorization = true; } /** - * Same as GattCharacrteristic::setWriteAuthorizationCallback(), but it allows - * the possibility to add an object reference and member function as - * handler for connection event callbacks. + * Register a callback handling client's write requests or commands. * - * @param[in] object - * Pointer to the object of a class defining the member callback - * function (@p member). - * @param[in] member - * The member callback (within the context of an object) to be - * invoked. + * The callback registered will be invoked when client attempts to write the + * characteristic value; the event handler can accept or reject the write + * request with the appropriate error code. + * + * @param[in] object Pointer to the object of a class defining the event + * handler (@p member). It must remain valid for the lifetime of the + * GattCharacteristic. + * @param[in] member The member function which handles the write event. */ template - void setWriteAuthorizationCallback(T *object, void (T::*member)(GattWriteAuthCallbackParams *)) { + void setWriteAuthorizationCallback( + T *object, + void (T::*member)(GattWriteAuthCallbackParams *) + ) { writeAuthorizationCallback.attach(object, member); enabledWriteAuthorization = true; } /** - * Set up callback that will be triggered before the GATT Client is allowed - * to read this characteristic. The handler determines the - * authorization reply for the read. + * Register the read requests event handler. * - * @param[in] callback - * Event handler being registered. + * The callback registered will be invoked when client attempts to read the + * characteristic value; the event handler can accept or reject the read + * request with the appropriate error code. It can also set specific outgoing + * data. + * + * @param[in] callback Event handler being registered. */ - void setReadAuthorizationCallback(void (*callback)(GattReadAuthCallbackParams *)) { + void setReadAuthorizationCallback( + void (*callback)(GattReadAuthCallbackParams *) + ) { readAuthorizationCallback.attach(callback); enabledReadAuthorization = true; } /** - * Same as GattCharacrteristic::setReadAuthorizationCallback(), but it allows - * the possibility to add an object reference and member function as - * handler for connection event callbacks. + * Register the read requests event handler. * - * @param[in] object - * Pointer to the object of a class defining the member callback - * function (@p member). - * @param[in] member - * The member callback (within the context of an object) to be - * invoked. + * The callback registered will be invoked when client attempts to read the + * characteristic value; the event handler can accept or reject the read + * request with the appropriate error code. It can also set specific outgoing + * data. + * + * @param[in] object Pointer to the object of a class defining the event + * handler (@p member). It must remain valid for the lifetime of the + * GattCharacteristic. + * @param[in] member The member function which handles the read event. */ template - void setReadAuthorizationCallback(T *object, void (T::*member)(GattReadAuthCallbackParams *)) { + void setReadAuthorizationCallback( + T *object, + void (T::*member)(GattReadAuthCallbackParams *) + ) { readAuthorizationCallback.attach(object, member); enabledReadAuthorization = true; } /** - * Helper that calls the registered handler to determine the authorization - * reply for a write request. This function is meant to be called from the - * BLE stack specific implementation. + * Invoke the write authorization callback. * - * @param[in] params - * To capture the context of the write-auth request. Also - * contains an out-parameter for reply. + * This function is an helper that calls the registered write handler to + * determine the authorization reply for a write request. + * + * @important This function is not meant to be called by user code. + * + * @param[in] params Context of the write-auth request; it contains an + * out-parameter used as a reply. * * @return A GattAuthCallbackReply_t value indicating whether authorization - * is granted. + * is granted. */ - GattAuthCallbackReply_t authorizeWrite(GattWriteAuthCallbackParams *params) { + GattAuthCallbackReply_t authorizeWrite(GattWriteAuthCallbackParams *params) + { if (!isWriteAuthorizationEnabled()) { return AUTH_CALLBACK_REPLY_SUCCESS; } - params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS; /* Initialized to no-error by default. */ + /* Initialized to no-error by default. */ + params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS; writeAuthorizationCallback.call(params); return params->authorizationReply; } /** - * Helper that calls the registered handler to determine the authorization - * reply for a read request. This function is meant to be called from the - * BLE stack specific implementation. + * Invoke the read authorization callback. * - * @param[in] params - * To capture the context of the read-auth request. + * This function is an helper that calls the registered read handler to + * determine the authorization reply for a read request. + * + * @important This function is not meant to be called by user code. + * + * @param[in] params Context of the read-auth request; it contains an + * out-parameter used as a reply and the handler can fill it with outgoing + * data. * * @return A GattAuthCallbackReply_t value indicating whether authorization - * is granted. + * is granted. * - * @note To authorize or deny the read, the params->authorizationReply field - * should be set to AUTH_CALLBACK_REPLY_SUCCESS (authorize) or any - * of the AUTH_CALLBACK_REPLY_ATTERR_* values (deny). + * @note If the read request is approved and params->data remains NULL then + * the current characteristic value is used in the read response payload. * - * @note If the read is approved and params->data is unchanged (NULL), - * the current characteristic value is used. - * - * @note If the read is approved, a new value can be provided by setting - * the params->data pointer and params->len fields. + * @note If the read is approved an outgoing value can be specified directly + * by the event handler with the help of the fields + * GattReadAuthCallbackParams::data and GattReadAuthCallbackParams::len. */ - GattAuthCallbackReply_t authorizeRead(GattReadAuthCallbackParams *params) { + GattAuthCallbackReply_t authorizeRead(GattReadAuthCallbackParams *params) + { if (!isReadAuthorizationEnabled()) { return AUTH_CALLBACK_REPLY_SUCCESS; } - params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS; /* Initialized to no-error by default. */ + /* Initialized to no-error by default. */ + params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS; readAuthorizationCallback.call(params); return params->authorizationReply; } @@ -491,16 +1536,18 @@ public: * * @return A reference to the characteristic's value attribute. */ - GattAttribute& getValueAttribute() { + GattAttribute& getValueAttribute() + { return _valueAttribute; } /** - * A const alternative to GattCharacteristic::getValueAttribute(). + * Get the characteristic's value attribute. * * @return A const reference to the characteristic's value attribute. */ - const GattAttribute& getValueAttribute() const { + const GattAttribute& getValueAttribute() const + { return _valueAttribute; } @@ -509,19 +1556,23 @@ public: * * @return The value attribute handle. * - * @note The underlying BLE stack typically assigns the attribute handle. + * @note The underlying BLE stack assigns the attribute handle when the + * enclosing service is added. */ - GattAttribute::Handle_t getValueHandle(void) const { + GattAttribute::Handle_t getValueHandle(void) const + { return getValueAttribute().getHandle(); } /** - * Get the characteristic's properties. Refer to - * GattCharacteristic::Properties_t. + * Get the characteristic's properties. + * + * @note Refer to GattCharacteristic::Properties_t. * * @return The characteristic's properties. */ - uint8_t getProperties(void) const { + uint8_t getProperties(void) const + { return _properties; } @@ -530,7 +1581,8 @@ public: * * @return The characteristic's required security. */ - SecurityManager::SecurityMode_t getRequiredSecurity() const { + SecurityManager::SecurityMode_t getRequiredSecurity() const + { return _requiredSecurity; } @@ -539,43 +1591,48 @@ public: * * @return The total number of descriptors. */ - uint8_t getDescriptorCount(void) const { + uint8_t getDescriptorCount(void) const + { return _descriptorCount; } /** - * Check whether read authorization is enabled. In other words, check whether a - * read authorization callback was previously registered. Refer to - * GattCharacteristic::setReadAuthorizationCallback(). + * Check whether read authorization is enabled. * - * @return true if read authorization is enabled, false otherwise. + * Read authorization is enabled when a read authorization event handler is + * setup. + * + * @return true if read authorization is enabled and false otherwise. */ - bool isReadAuthorizationEnabled() const { + bool isReadAuthorizationEnabled() const + { return enabledReadAuthorization; } /** - * Check whether write authorization is enabled. In other words, check whether a - * write authorization callback was previously registered. Refer to - * GattCharacteristic::setWriteAuthorizationCallback(). + * Check whether write authorization is enabled. + * + * Write authorization is enabled when a write authorization event handler is + * setup. * * @return true if write authorization is enabled, false otherwise. */ - bool isWriteAuthorizationEnabled() const { + bool isWriteAuthorizationEnabled() const + { return enabledWriteAuthorization; } /** * Get this characteristic's descriptor at a specific index. * - * @param[in] index - * The descriptor's index. + * @param[in] index The index of the descriptor to get. * - * @return A pointer the requested descriptor if @p index contains a valid - * descriptor, or NULL otherwise. + * @return A pointer the requested descriptor if @p index is within the + * range of the descriptor array or NULL otherwise. */ - GattAttribute *getDescriptor(uint8_t index) { - if (index >= _descriptorCount) { + GattAttribute *getDescriptor(uint8_t index) + { + if (index = _descriptorCount) { return NULL; } @@ -586,45 +1643,50 @@ private: /** * Attribute that contains the actual value of this characteristic. */ - GattAttribute _valueAttribute; + GattAttribute _valueAttribute; + /** * The characteristic's properties. Refer to * GattCharacteristic::Properties_t. */ - uint8_t _properties; + uint8_t _properties; + /** * The characteristic's required security. */ - SecurityManager::SecurityMode_t _requiredSecurity; + SecurityManager::SecurityMode_t _requiredSecurity; + /** * The characteristic's descriptor attributes. - * This contains only CCCDs that has neither the notify nor the indicate - * flag set, as the underlying BLE stack handles those. */ - GattAttribute **_descriptors; + GattAttribute **_descriptors; + /** * The number of descriptors in this characteristic. */ - uint8_t _descriptorCount; + uint8_t _descriptorCount; /** - * Whether read authorization is enabled - in other words, whether there is a registered - * callback to determine read authorization reply. + * Whether read authorization is enabled. */ bool enabledReadAuthorization; + /** - * Whether write authorization is enabled - in other words, whether there is a registered - * callback to determine write authorization reply. + * Whether write authorization is enabled. */ bool enabledWriteAuthorization; + /** * The registered callback handler for read authorization reply. */ - FunctionPointerWithContext readAuthorizationCallback; + FunctionPointerWithContext + readAuthorizationCallback; + /** * The registered callback handler for write authorization reply. */ - FunctionPointerWithContext writeAuthorizationCallback; + FunctionPointerWithContext + writeAuthorizationCallback; private: /* Disallow copy and assignment. */ @@ -633,7 +1695,7 @@ private: }; /** - * Helper class to construct a read-only GattCharacteristic. + * Helper class that represents a read only GattCharacteristic. */ template class ReadOnlyGattCharacteristic : public GattCharacteristic { @@ -641,37 +1703,42 @@ public: /** * Construct a ReadOnlyGattCharacteristic. * - * @param[in] uuid - * The characteristic's UUID. - * @param[in] valuePtr - * Pointer to the characteristic's initial value. - * @param[in] additionalProperties - * Additional characteristic properties. By default, the - * properties are set to - * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. - * @param[in] descriptors - * An array of pointers to descriptors to be added to the new - * characteristic. - * @param[in] numDescriptors - * The total number of descriptors in @p descriptors. + * @param[in] uuid The characteristic's UUID. + * @param[in] valuePtr Pointer to the characteristic's initial value. The + * pointer is reinterpreted as a pointer to an uint8_t buffer. + * @param[in] additionalProperties Additional characteristic properties. By + * default, the properties are set to + * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. + * @param[in] descriptors An array of pointers to descriptors to be added + * to the new characteristic. + * @param[in] numDescriptors The total number of descriptors in @p + * descriptors. * * @note Instances of ReadOnlyGattCharacteristic have a fixed length - * attribute value that equals sizeof(T). For a variable length - * alternative use GattCharacteristic directly. + * attribute value that equals sizeof(T). For a variable length alternative + * use GattCharacteristic directly. */ - ReadOnlyGattCharacteristic(const UUID &uuid, - T *valuePtr, - uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, - GattAttribute *descriptors[] = NULL, - unsigned numDescriptors = 0) : - GattCharacteristic(uuid, reinterpret_cast(valuePtr), sizeof(T), sizeof(T), - BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties, descriptors, numDescriptors, false) { - /* empty */ + ReadOnlyGattCharacteristic( + const UUID &uuid, + T *valuePtr, + uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, + GattAttribute *descriptors[] = NULL, + unsigned numDescriptors = 0 + ) : GattCharacteristic( + uuid, + reinterpret_cast(valuePtr), + sizeof(T), + sizeof(T), + BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties, + descriptors, + numDescriptors, + false + ) { } }; /** - * Helper class to construct a write-only GattCharacteristic. + * Helper class that represents a write only GattCharacteristic. */ template class WriteOnlyGattCharacteristic : public GattCharacteristic { @@ -679,37 +1746,41 @@ public: /** * Construct a WriteOnlyGattCharacteristic. * - * @param[in] uuid - * The characteristic's UUID. - * @param[in] valuePtr - * Pointer to the characteristic's initial value. - * @param[in] additionalProperties - * Additional characteristic properties. By default, the - * properties are set to - * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE. - * @param[in] descriptors - * An array of pointers to descriptors to be added to the new - * characteristic. - * @param[in] numDescriptors - * The total number of descriptors in @p descriptors. + * @param[in] uuid The characteristic's UUID. + * @param[in] valuePtr Pointer to the characteristic's initial value. The + * pointer is reinterpreted as a pointer to an uint8_t buffer. + * @param[in] additionalProperties Additional characteristic properties. By + * default, the properties are set to + * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE. + * @param[in] descriptors An array of pointers to descriptors to be added to + * the new characteristic. + * @param[in] numDescriptors The total number of descriptors in @p + * descriptors. * * @note Instances of WriteOnlyGattCharacteristic have variable length - * attribute value with maximum size equal to sizeof(T). For a fixed length - * alternative, use GattCharacteristic directly. + * attribute value with maximum size equal to sizeof(T). For a fixed length + * alternative, use GattCharacteristic directly. */ - WriteOnlyGattCharacteristic(const UUID &uuid, - T *valuePtr, - uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, - GattAttribute *descriptors[] = NULL, - unsigned numDescriptors = 0) : - GattCharacteristic(uuid, reinterpret_cast(valuePtr), sizeof(T), sizeof(T), - BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, descriptors, numDescriptors) { - /* empty */ + WriteOnlyGattCharacteristic( + const UUID &uuid, + T *valuePtr, + uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, + GattAttribute *descriptors[] = NULL, + unsigned numDescriptors = 0 + ) : GattCharacteristic( + uuid, + reinterpret_cast(valuePtr), + sizeof(T), + sizeof(T), + BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, + descriptors, + numDescriptors + ) { } }; /** - * Helper class to construct a readable and writable GattCharacteristic. + * Helper class that represents a readable and writable GattCharacteristic. */ template class ReadWriteGattCharacteristic : public GattCharacteristic { @@ -717,38 +1788,41 @@ public: /** * Construct a ReadWriteGattCharacteristic. * - * @param[in] uuid - * The characteristic's UUID. - * @param[in] valuePtr - * Pointer to the characteristic's initial value. - * @param[in] additionalProperties - * Additional characteristic properties. By default, the - * properties are set to - * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE | - * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. - * @param[in] descriptors - * An array of pointers to descriptors to be added to the new - * characteristic. - * @param[in] numDescriptors - * The total number of descriptors in @p descriptors. + * @param[in] uuid The characteristic's UUID. + * @param[in] valuePtr Pointer to the characteristic's initial value. The + * pointer is reinterpreted as a pointer to an uint8_t buffer. + * @param[in] additionalProperties Additional characteristic properties. By + * default, the properties are set to + * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE and + * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. + * @param[in] descriptors An array of pointers to descriptors to be added to + * the new characteristic. + * @param[in] numDescriptors The total number of descriptors in @p descriptors. * * @note Instances of ReadWriteGattCharacteristic have variable length - * attribute value with maximum size equal to sizeof(T). For a fixed length - * alternative, use GattCharacteristic directly. + * attribute value with maximum size equal to sizeof(T). For a fixed length + * alternative, use GattCharacteristic directly. */ - ReadWriteGattCharacteristic(const UUID &uuid, - T *valuePtr, - uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, - GattAttribute *descriptors[] = NULL, - unsigned numDescriptors = 0) : - GattCharacteristic(uuid, reinterpret_cast(valuePtr), sizeof(T), sizeof(T), - BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, descriptors, numDescriptors) { - /* empty */ + ReadWriteGattCharacteristic( + const UUID &uuid, + T *valuePtr, + uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, + GattAttribute *descriptors[] = NULL, + unsigned numDescriptors = 0 + ) : GattCharacteristic( + uuid, + reinterpret_cast(valuePtr), + sizeof(T), + sizeof(T), + BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, + descriptors, + numDescriptors + ) { } }; /** - * Helper class to construct a write-only GattCharacteristic with an array + * Helper class that represents a write-only GattCharacteristic with an array * value. */ template @@ -757,38 +1831,41 @@ public: /** * Construct a WriteOnlyGattCharacteristic. * - * @param[in] uuid - * The characteristic's UUID. - * @param[in] valuePtr - * Pointer to an array of length NUM_ELEMENTS containing the - * characteristic's intitial value. - * @param[in] additionalProperties - * Additional characteristic properties. By default, the - * properties are set to - * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE. - * @param[in] descriptors - * An array of pointers to descriptors to be added to the new - * characteristic. - * @param[in] numDescriptors - * The total number of descriptors in @p descriptors. + * @param[in] uuid The characteristic's UUID. + * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing + * the characteristic's initial value. The pointer is reinterpreted as a + * pointer to an uint8_t buffer. + * @param[in] additionalProperties Additional characteristic properties. By + * default, the properties are set to + * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE. + * @param[in] descriptors An array of pointers to descriptors to be added to + * the new characteristic. + * @param[in] numDescriptors The total number of descriptors in @p descriptors. * * @note Instances of WriteOnlyGattCharacteristic have variable length - * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS. - * For a fixed length alternative, use GattCharacteristic directly. + * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS. + * For a fixed length alternative, use GattCharacteristic directly. */ - WriteOnlyArrayGattCharacteristic(const UUID &uuid, - T valuePtr[NUM_ELEMENTS], - uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, - GattAttribute *descriptors[] = NULL, - unsigned numDescriptors = 0) : - GattCharacteristic(uuid, reinterpret_cast(valuePtr), sizeof(T) * NUM_ELEMENTS, sizeof(T) * NUM_ELEMENTS, - BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, descriptors, numDescriptors) { - /* empty */ + WriteOnlyArrayGattCharacteristic( + const UUID &uuid, + T valuePtr[NUM_ELEMENTS], + uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, + GattAttribute *descriptors[] = NULL, + unsigned numDescriptors = 0 + ) : GattCharacteristic( + uuid, + reinterpret_cast(valuePtr), + sizeof(T) * NUM_ELEMENTS, + sizeof(T) * NUM_ELEMENTS, + BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, + descriptors, + numDescriptors + ) { } }; /** - * Helper class to construct a read-only GattCharacteristic with an array + * Helper class that represents a read-only GattCharacteristic with an array * value. */ template @@ -797,39 +1874,44 @@ public: /** * Construct a ReadOnlyGattCharacteristic. * - * @param[in] uuid - * The characteristic's UUID. - * @param[in] valuePtr - * Pointer to an array of length NUM_ELEMENTS containing the - * characteristic's intitial value. - * @param[in] additionalProperties - * Additional characteristic properties. By default, the - * properties are set to - * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. - * @param[in] descriptors - * An array of pointers to descriptors to be added to the new - * characteristic. - * @param[in] numDescriptors - * The total number of descriptors in @p descriptors. + * @param[in] uuid The characteristic's UUID. + * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing + * the characteristic's initial value. The pointer is reinterpreted as a + * pointer to an uint8_t buffer. + * @param[in] additionalProperties Additional characteristic properties. By + * default, the properties are set to + * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. + * @param[in] descriptors An array of pointers to descriptors to be added to + * the new characteristic. + * @param[in] numDescriptors The total number of descriptors in @p + * descriptors. * * @note Instances of ReadOnlyGattCharacteristic have fixed length - * attribute value that equals sizeof(T) * NUM_ELEMENTS. - * For a variable length alternative, use GattCharacteristic directly. + * attribute value that equals sizeof(T) * NUM_ELEMENTS. For a variable + * length alternative, use GattCharacteristic directly. */ - ReadOnlyArrayGattCharacteristic(const UUID &uuid, - T valuePtr[NUM_ELEMENTS], - uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, - GattAttribute *descriptors[] = NULL, - unsigned numDescriptors = 0) : - GattCharacteristic(uuid, reinterpret_cast(valuePtr), sizeof(T) * NUM_ELEMENTS, sizeof(T) * NUM_ELEMENTS, - BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties, descriptors, numDescriptors, false) { - /* empty */ + ReadOnlyArrayGattCharacteristic( + const UUID &uuid, + T valuePtr[NUM_ELEMENTS], + uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, + GattAttribute *descriptors[] = NULL, + unsigned numDescriptors = 0 + ) : GattCharacteristic( + uuid, + reinterpret_cast(valuePtr), + sizeof(T) * NUM_ELEMENTS, + sizeof(T) * NUM_ELEMENTS, + BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties, + descriptors, + numDescriptors, + false + ) { } }; /** - * Helper class to construct a readable and writable GattCharacteristic with an array - * value. + * Helper class that represents a readable and writable GattCharacteristic with + * an array value. */ template class ReadWriteArrayGattCharacteristic : public GattCharacteristic { @@ -837,34 +1919,37 @@ public: /** * Construct a ReadWriteGattCharacteristic. * - * @param[in] uuid - * The characteristic's UUID. - * @param[in] valuePtr - * Pointer to an array of length NUM_ELEMENTS containing the - * characteristic's intitial value. - * @param[in] additionalProperties - * Additional characteristic properties. By default, the - * properties are set to - * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE | - * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. - * @param[in] descriptors - * An array of pointers to descriptors to be added to the new - * characteristic. - * @param[in] numDescriptors - * The total number of descriptors in @p descriptors. + * @param[in] uuid The characteristic's UUID. + * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing + * the characteristic's initial value. The pointer is reinterpreted as a + * pointer to an uint8_t buffer. + * @param[in] additionalProperties Additional characteristic properties. By + * default, the properties are set to + * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE | + * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. + * @param[in] descriptors An array of pointers to descriptors to be added to + * the new characteristic. + * @param[in] numDescriptors The total number of descriptors in @p descriptors. * * @note Instances of ReadWriteGattCharacteristic have variable length - * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS. - * For a fixed length alternative, use GattCharacteristic directly. + * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS. + * For a fixed length alternative, use GattCharacteristic directly. */ - ReadWriteArrayGattCharacteristic(const UUID &uuid, - T valuePtr[NUM_ELEMENTS], - uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, - GattAttribute *descriptors[] = NULL, - unsigned numDescriptors = 0) : - GattCharacteristic(uuid, reinterpret_cast(valuePtr), sizeof(T) * NUM_ELEMENTS, sizeof(T) * NUM_ELEMENTS, - BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, descriptors, numDescriptors) { - /* empty */ + ReadWriteArrayGattCharacteristic( + const UUID &uuid, + T valuePtr[NUM_ELEMENTS], + uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE, + GattAttribute *descriptors[] = NULL, + unsigned numDescriptors = 0 + ) : GattCharacteristic( + uuid, + reinterpret_cast(valuePtr), + sizeof(T) * NUM_ELEMENTS, + sizeof(T) * NUM_ELEMENTS, + BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, + descriptors, + numDescriptors + ) { } }; diff --git a/features/FEATURE_BLE/ble/GattServer.h b/features/FEATURE_BLE/ble/GattServer.h index c7a27f89cf..09b5663a67 100644 --- a/features/FEATURE_BLE/ble/GattServer.h +++ b/features/FEATURE_BLE/ble/GattServer.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __GATT_SERVER_H__ -#define __GATT_SERVER_H__ +#ifndef MBED_GATT_SERVER_H__ +#define MBED_GATT_SERVER_H__ #include "Gap.h" #include "GattService.h" @@ -33,52 +33,129 @@ * @{ */ +/** + * Construct and operates a GATT server. + * + * A Gatt server is a collection of GattService; these services contains + * characteristics that may be read or written by a peer connected to the device. + * These characteristics may also emits updates to subscribed clients when their + * value change. + * + * @p Server Layout + * + * Application code can add GattService object to the server with the help of + * the function addService(). That function registers all the GattCharacteristic + * enclosed in the service as well as all the characteristics descriptors (see + * GattAttribute) these characteristics contain. Service registration assign + * a unique handle to the various attributes being part of the service; this + * handle should be used for subsequent read or write of these components. + * + * There is no primitives defined to remove a single service; however a call to + * the function reset() will remove all services previously registered in the + * GattServer. + * + * @p Characteristic and attributes access + * + * Values of the characteristic and the characteristic descriptor present in the + * GattServer must be accessed via the handle assigned to them when the service + * has been registered; the GattServer class offers several flavors of read() + * and write() function that retrieve or mutate an attribute value. + * + * Application code can query if a client has subscribed to a given + * characteristic's value update by invoking the function areUpdatesEnabled(). + * + * @p Events + * + * The GattServer allows application code to register several event handler that + * can be used to monitor client and server activities: + * - onDataSent(): Register an event handler that will be called when a + * characteristic value update has been sent to a client. + * - onDataWriten(): Register an event handler that will be called when a + * client has written an attribute of the server. + * - onDataRead(): Register an event handler that will be called when a + * client has read an attribute of the server. + * - onUpdatesEnabled: Register an event handler that will be called when a + * client subscribes to updates of a characteristic. + * - onUpdatesDisabled: Register an event handler that will be called when a + * client unsubscribes from updates of a characteristic. + * - onConfimationReceived: Register an event handler that will be called + * when a client acknowledge a characteristic value notification. + * + * @note The term characteristic value update is used to represents + * Characteristic Value Notification and Characteristic Value Indication when + * the nature of the server initiated is not relevant. + */ class GattServer { public: /** - * Type for the registered callbacks added to the data sent callchain. - * Refer to GattServer::onDataSent(). + * Event handler invoked when the server has sent data to a client. + * + * @see onDataSent(). */ typedef FunctionPointerWithContext DataSentCallback_t; - /** - * Type for the data sent event callchain. Refer to GattServer::onDataSent(). - */ - typedef CallChainOfFunctionPointersWithContext DataSentCallbackChain_t; /** - * Type for the registered callbacks added to the data written callchain. - * Refer to GattServer::onDataWritten(). + * Callchain of DataSentCallback_t objects. + * + * @see onDataSent(). */ - typedef FunctionPointerWithContext DataWrittenCallback_t; - /** - * Type for the data written event callchain. Refer to GattServer::onDataWritten(). - */ - typedef CallChainOfFunctionPointersWithContext DataWrittenCallbackChain_t; + typedef CallChainOfFunctionPointersWithContext + DataSentCallbackChain_t; /** - * Type for the registered callbacks added to the data read callchain. - * Refer to GattServer::onDataRead(). + * Event handler invoked when the client has written an attribute of the + * server. + * + * @see onDataWritten(). */ - typedef FunctionPointerWithContext DataReadCallback_t; - /** - * Type for the data read event callchain. Refer to GattServer::onDataRead(). - */ - typedef CallChainOfFunctionPointersWithContext DataReadCallbackChain_t; + typedef FunctionPointerWithContext + DataWrittenCallback_t; /** - * Type for the registered callbacks added to the shutdown callchain. - * Refer to GattServer::onShutdown(). + * Callchain of DataWrittenCallback_t objects. + * + * @see onDataWritten(). */ - typedef FunctionPointerWithContext GattServerShutdownCallback_t; - /** - * Type for the shutdown event callchain. Refer to GattServer::onShutdown(). - */ - typedef CallChainOfFunctionPointersWithContext GattServerShutdownCallbackChain_t; + typedef CallChainOfFunctionPointersWithContext + DataWrittenCallbackChain_t; /** - * Type for the registered callback for various events. Refer to - * GattServer::onUpdatesEnabled(), GattServer::onUpdateDisabled() and - * GattServer::onConfirmationReceived(). + * Event handler invoked when the client has read an attribute of the server. + * + * @see onDataRead(). + */ + typedef FunctionPointerWithContext + DataReadCallback_t; + + /** + * Callchain of DataReadCallback_t. + * + * @see onDataRead(). + */ + typedef CallChainOfFunctionPointersWithContext + DataReadCallbackChain_t; + + /** + * Event handler invoked when the GattServer is reset. + * + * @see onShutdown() reset() + */ + typedef FunctionPointerWithContext + GattServerShutdownCallback_t; + + /** + * Callchain of GattServerShutdownCallback_t. + * + * @see onShutdown() reset() + */ + typedef CallChainOfFunctionPointersWithContext + GattServerShutdownCallbackChain_t; + + /** + * Event handler that handle subscription to characteristic updates, + * unsubscription from characteristic updates and notification confirmation. + * + * @see onUpdatesEnabled() onUpdateDisabled() onConfirmationReceived() */ typedef FunctionPointerWithContext EventCallback_t; @@ -95,138 +172,175 @@ protected: updatesEnabledCallback(NULL), updatesDisabledCallback(NULL), confirmationReceivedCallback(NULL) { - /* empty */ } /* - * The following functions are meant to be overridden in the platform-specific subclass. + * The following functions are meant to be overridden in the platform + * specific subclass. */ public: /** - * Add a service declaration to the local server ATT table. Also add the - * characteristics contained within. + * Add a service declaration to the local attribute server table. * - * @param[in] service - * The service to be added. + * This functions inserts a service declaration in the attribute table + * followed by the characteristic declarations (including characteristic + * descriptors) present in @p service. + * + * The process assign a unique attribute handle to all the elements added + * into the attribute table. This handle is an ID that must be used for + * subsequent interractions with the elements. + * + * @note Their is no mirror function that removes a single service. + * Application code can remove all the registered services by calling + * reset(). + * + * @important Service, characteristics and descriptors objects registered + * within the GattServer must remain reachable until reset() is called. + * + * @param[in] service The service to be added; attribute handle of services, + * characteristic and characteristic descriptors will be updated by the + * process. * * @return BLE_ERROR_NONE if the service was successfully added. */ - virtual ble_error_t addService(GattService &service) { + virtual ble_error_t addService(GattService &service) + { /* Avoid compiler warnings about unused variables. */ (void)service; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Read the value of a characteristic from the local GATT server. + * Read the value of an attribute present in the local GATT server. * - * @param[in] attributeHandle - * Attribute handle for the value attribute of the characteristic. - * @param[out] buffer - * A buffer to hold the value being read. - * @param[in,out] lengthP - * Length of the buffer being supplied. If the attribute - * value is longer than the size of the supplied buffer, - * this variable holds upon return the total attribute value length - * (excluding offset). The application may use this - * information to allocate a suitable buffer size. + * @param[in] attributeHandle Handle of the attribute to read. + * @param[out] buffer A buffer to hold the value being read. + * @param[in,out] lengthP Length of the buffer being supplied. If the + * attribute value is longer than the size of the supplied buffer, this + * variable holds upon return the total attribute value length (excluding + * offset). The application may use this information to allocate a suitable + * buffer size. * * @return BLE_ERROR_NONE if a value was read successfully into the buffer. + * + * @important read(Gap::Handle_t, GattAttribute::Handle_t, uint8_t *, uint16_t *) + * must be used to read Client Characteristic Configuration Descriptor (CCCD) + * because the value of this type of attribute depends on the connection. */ - virtual ble_error_t read(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP) { + virtual ble_error_t read( + GattAttribute::Handle_t attributeHandle, + uint8_t buffer[], + uint16_t *lengthP + ) { /* Avoid compiler warnings about unused variables. */ (void)attributeHandle; (void)buffer; (void)lengthP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Read the value of a characteristic from the local GATT server. + * Read the value of an attribute present in the local GATT server. * - * @param[in] connectionHandle - * Connection handle. - * @param[in] attributeHandle - * Attribute handle for the value attribute of the characteristic. - * @param[out] buffer - * A buffer to hold the value being read. - * @param[in,out] lengthP - * Length of the buffer being supplied. If the attribute - * value is longer than the size of the supplied buffer, - * this variable holds upon return the total attribute value length - * (excluding offset). The application may use this - * information to allocate a suitable buffer size. + * The connection handle allows application code to read the value of a + * Client Characteristic Configuration Descriptor for a given connection. + * + * @param[in] connectionHandle Connection handle. + * @param[in] attributeHandle Attribute handle for the value attribute of + * the characteristic. + * @param[out] buffer A buffer to hold the value being read. + * @param[in,out] lengthP Length of the buffer being supplied. If the + * attribute value is longer than the size of the supplied buffer, this + * variable holds upon return the total attribute value length (excluding + * offset). The application may use this information to allocate a suitable + * buffer size. * * @return BLE_ERROR_NONE if a value was read successfully into the buffer. - * - * @note This API is a version of the above, with an additional connection handle - * parameter to allow fetches for connection-specific multivalued - * attributes (such as the CCCDs). */ - virtual ble_error_t read(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) { + virtual ble_error_t read( + Gap::Handle_t connectionHandle, + GattAttribute::Handle_t attributeHandle, + uint8_t *buffer, + uint16_t *lengthP + ) { /* Avoid compiler warnings about unused variables. */ (void)connectionHandle; (void)attributeHandle; (void)buffer; (void)lengthP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Update the value of a characteristic on the local GATT server. + * Update the value of an attribute present in the local GATT server. * - * @param[in] attributeHandle - * Handle for the value attribute of the characteristic. - * @param[in] value - * A pointer to a buffer holding the new value. - * @param[in] size - * Size of the new value (in bytes). - * @param[in] localOnly - * Should this update be kept on the local - * GATT server regardless of the state of the - * notify/indicate flag in the CCCD for this - * Characteristic? If set to true, no notification - * or indication is generated. + * @param[in] attributeHandle Handle of the attribute to write. + * @param[in] value A pointer to a buffer holding the new value. + * @param[in] size Size in bytes of the new value (in bytes). + * @param[in] localOnly If this flag is false and the attribute handle + * written is a characteristic value then the server sends an update + * containing the new value to all clients that have subscribed to the + * characteristic's notifications or indications. Otherwise the update does + * not generate a single server initiated event. * - * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. + * @return BLE_ERROR_NONE if the attribute value has been successfully + * updated. */ - virtual ble_error_t write(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) { + virtual ble_error_t write( + GattAttribute::Handle_t attributeHandle, + const uint8_t *value, + uint16_t size, + bool localOnly = false + ) { /* Avoid compiler warnings about unused variables. */ (void)attributeHandle; (void)value; (void)size; (void)localOnly; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Update the value of a characteristic on the local GATT server. A version - * of the same as the above, with a connection handle parameter to allow updates - * for connection-specific multivalued attributes (such as the CCCDs). + * Update the value of an attribute present in the local GATT server. * - * @param[in] connectionHandle - * Connection handle. - * @param[in] attributeHandle - * Handle for the value attribute of the characteristic. - * @param[in] value - * A pointer to a buffer holding the new value. - * @param[in] size - * Size of the new value (in bytes). - * @param[in] localOnly - * Should this update be kept on the local - * GattServer regardless of the state of the - * notify/indicate flag in the CCCD for this - * Characteristic? If set to true, no notification - * or indication is generated. + * The connection handle parameter allows application code to direct + * notification or indication resulting from the update to a specific client. * - * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. + * @param[in] connectionHandle Connection handle. + * @param[in] attributeHandle Handle for the value attribute of the + * characteristic. + * @param[in] value A pointer to a buffer holding the new value. + * @param[in] size Size of the new value (in bytes). + * @param[in] localOnly If this flag is false and the attribute handle + * written is a characteristic value then the server sends an update + * containing the new value to the client identified by the parameter + * @p connectionHandle if it is subscribed to the characteristic's + * notifications or indications. Otherwise the update does not generate a + * single server initiated event. + * + * @return BLE_ERROR_NONE if the attribute value has been successfully + * updated. */ - virtual ble_error_t write(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) { + virtual ble_error_t write( + Gap::Handle_t connectionHandle, + GattAttribute::Handle_t attributeHandle, + const uint8_t *value, + uint16_t size, + bool localOnly = false + ) { /* Avoid compiler warnings about unused variables. */ (void)connectionHandle; (void)attributeHandle; @@ -234,56 +348,77 @@ public: (void)size; (void)localOnly; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Determine the updates-enabled status (notification or indication) for the current connection from a characteristic's CCCD. + * Determine if one of the connected clients has subscribed to notifications + * or indications of the characteristic in input. * - * @param[in] characteristic - * The characteristic. - * @param[out] enabledP - * Upon return, *enabledP is true if updates are enabled, else false. + * @param[in] characteristic The characteristic. + * @param[out] enabledP Upon return, *enabledP is true if updates are + * enabled for a connected client; otherwise *enabledP is false. * - * @return BLE_ERROR_NONE if the connection and handle are found. False otherwise. + * @return BLE_ERROR_NONE if the connection and handle are found. False + * otherwise. */ - virtual ble_error_t areUpdatesEnabled(const GattCharacteristic &characteristic, bool *enabledP) { + virtual ble_error_t areUpdatesEnabled( + const GattCharacteristic &characteristic, + bool *enabledP + ) { /* Avoid compiler warnings about unused variables. */ (void)characteristic; (void)enabledP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Determine the connection-specific updates-enabled status (notification or indication) from a characteristic's CCCD. + * Determine if an identified client has subscribed to notifications or + * indications of a given characteristic. * - * @param[in] connectionHandle - * The connection handle. - * @param[in] characteristic - * The characteristic. - * @param[out] enabledP - * Upon return, *enabledP is true if updates are enabled, else false. + * @param[in] connectionHandle The connection handle. + * @param[in] characteristic The characteristic. + * @param[out] enabledP Upon return, *enabledP is true if the client + * identified by @p connectionHandle has subscribed to notifications or + * indications of @p characteristic; otherwise *enabledP is false. * - * @return BLE_ERROR_NONE if the connection and handle are found. False otherwise. + * @return BLE_ERROR_NONE if the connection and handle are found. False + * otherwise. */ - virtual ble_error_t areUpdatesEnabled(Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP) { + virtual ble_error_t areUpdatesEnabled( + Gap::Handle_t connectionHandle, + const GattCharacteristic &characteristic, + bool *enabledP + ) { /* Avoid compiler warnings about unused variables. */ (void)connectionHandle; (void)characteristic; (void)enabledP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * A virtual function to allow underlying stacks to indicate if they support - * onDataRead(). It should be overridden to return true as applicable. + * Indicate if the underlying stack emit events when an attribute is read by + * a client. * - * @return true if onDataRead is supported, false otherwise. + * @important This function should be overridden to return true if + * applicable. + * + * @return true if onDataRead is supported; false otherwise. */ - virtual bool isOnDataReadAvailable() const { - return false; /* Requesting action from porters: override this API if this capability is supported. */ + virtual bool isOnDataReadAvailable() const + { + /* Requesting action from porters: override this API if this capability + is supported. */ + return false; } /* @@ -291,128 +426,111 @@ public: */ public: /** - * Add a callback for the GATT event DATA_SENT (which is triggered when - * GATT sends updates in the form of notifications). + * Add an event handler that monitors emission of characteristic value + * updates. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. * * @note It is possible to chain together multiple onDataSent callbacks - * (potentially from different modules of an application) to receive updates - * to characteristics. - * - * @note It is also possible to set up a callback into a member function of - * some object. + * (potentially from different modules of an application). */ - void onDataSent(const DataSentCallback_t& callback) { + void onDataSent(const DataSentCallback_t &callback) + { dataSentCallChain.add(callback); } /** - * Same as GattServer::onDataSent() but it allows the possibility to add an object - * reference and member function as handler for DATA_SENT event - * callbacks. + * Add an event handler that monitors emission of characteristic value + * updates. * - * @param[in] objPtr - * Pointer to the object of a class defining the member callback - * function (@p memberPtr). - * @param[in] memberPtr - * The member callback (within the context of an object) to be - * invoked. + * @param[in] objPtr Pointer to the instance that will be used to invoke the + * event handler. + * @param[in] memberPtr Event handler being registered. It is a member + * function. */ template - void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) { + void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) + { dataSentCallChain.add(objPtr, memberPtr); } /** - * @brief Provide access to the callchain of DATA_SENT event callbacks. + * Access the callchain of data sent event handlers. * * @return A reference to the DATA_SENT event callback chain. */ - DataSentCallbackChain_t& onDataSent() { + DataSentCallbackChain_t &onDataSent() + { return dataSentCallChain; } /** - * Set up a callback for when an attribute has its value updated by or at the - * connected peer. For a peripheral, this callback is triggered when the local - * GATT server has an attribute updated by a write command from the peer. - * For a central, this callback is triggered when a response is received for - * a write request. + * Set an event handler that will be called after an attribute has been + * written by a connected peer. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback The event handler being registered. * - * @note It is possible to chain together multiple onDataWritten callbacks - * (potentially from different modules of an application) to receive updates - * to characteristics. Many services, such as DFU and UART, add their own - * onDataWritten callbacks behind the scenes to trap interesting events. - * - * @note It is also possible to set up a callback into a member function of - * some object. - * - * @note It is possible to unregister a callback using onDataWritten().detach(callback) + * @important It is possible to set multiple event handlers. Registered + * handlers may be removed with onDataWritten().detach(callback). */ - void onDataWritten(const DataWrittenCallback_t& callback) { + void onDataWritten(const DataWrittenCallback_t &callback) + { dataWrittenCallChain.add(callback); } /** - * Same as GattServer::onDataWritten() but it allows the possibility to add an object - * reference and member function as a handler for data written event - * callbacks. + * Set an event handler that will be called after an attribute has been + * written by a connected peer. * - * @param[in] objPtr - * Pointer to the object of a class defining the member callback - * function (@p memberPtr). - * @param[in] memberPtr - * The member callback (within the context of an object) to be - * invoked. + * @param[in] objPtr Pointer to the instance that will be used to invoke the + * event handler (@p memberPtr). + * @param[in] memberPtr Event handler being registered. It is a member + * function. */ template - void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) { + void onDataWritten( + T *objPtr, + void (T::*memberPtr)(const GattWriteCallbackParams *context) + ) { dataWrittenCallChain.add(objPtr, memberPtr); } /** - * @brief Provide access to the callchain of data written event callbacks. + * Access the callchain of data written event handlers. * * @return A reference to the data written event callbacks chain. * - * @note It is possible to register callbacks using onDataWritten().add(callback). + * @note It is possible to register callbacks using + * onDataWritten().add(callback). * - * @note It is possible to unregister callbacks using onDataWritten().detach(callback). + * @note It is possible to unregister callbacks using + * onDataWritten().detach(callback). */ - DataWrittenCallbackChain_t& onDataWritten() { + DataWrittenCallbackChain_t &onDataWritten() + { return dataWrittenCallChain; } /** - * Set up a callback to be invoked on the peripheral when a remote client is - * reading an attribute. + * Set an event handler that monitors attribute reads from connected clients. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. * * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; - * else BLE_ERROR_NONE. + * else BLE_ERROR_NONE. * * @note This functionality may not be available on all underlying stacks. - * You could use GattCharacteristic::setReadAuthorizationCallback() as an - * alternative. Refer to isOnDataReadAvailable(). + * Application code may work around that limitation by monitoring read + * requests instead of read events. * - * @note It is possible to chain together multiple onDataRead callbacks - * (potentially from different modules of an application) to receive updates - * to characteristics. Services may add their own onDataRead callbacks - * behind the scenes to trap interesting events. + * @see GattCharacteristic::setReadAuthorizationCallback() + * @see isOnDataReadAvailable(). * - * @note It is also possible to set up a callback into a member function of - * some object. - * - * @note It is possible to unregister a callback using onDataRead().detach(callback). + * @important It is possible to set multiple event handlers. Registered + * handlers may be removed with onDataRead().detach(callback). */ - ble_error_t onDataRead(const DataReadCallback_t& callback) { + ble_error_t onDataRead(const DataReadCallback_t &callback) + { if (!isOnDataReadAvailable()) { return BLE_ERROR_NOT_IMPLEMENTED; } @@ -422,19 +540,18 @@ public: } /** - * Same as GattServer::onDataRead() but it allows the possibility to add an object - * reference and member function as handler for data read event - * callbacks. + * Set an event handler that monitors attribute reads from connected clients. * - * @param[in] objPtr - * Pointer to the object of a class defining the member callback - * function (@p memberPtr). - * @param[in] memberPtr - * The member callback (within the context of an object) to be - * invoked. + * @param[in] objPtr Pointer to the instance that will be used to invoke the + * event handler (@p memberPtr). + * @param[in] memberPtr Event handler being registered. It is a member + * function. */ template - ble_error_t onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) { + ble_error_t onDataRead( + T *objPtr, + void (T::*memberPtr)(const GattReadCallbackParams *context) + ) { if (!isOnDataReadAvailable()) { return BLE_ERROR_NOT_IMPLEMENTED; } @@ -444,99 +561,104 @@ public: } /** - * @brief Provide access to the callchain of data read event callbacks. + * Access the callchain of data read event handlers. * * @return A reference to the data read event callbacks chain. * - * @note It is possible to register callbacks using onDataRead().add(callback). + * @note It is possible to register callbacks using + * onDataRead().add(callback). * - * @note It is possible to unregister callbacks using onDataRead().detach(callback). + * @note It is possible to unregister callbacks using + * onDataRead().detach(callback). */ - DataReadCallbackChain_t& onDataRead() { + DataReadCallbackChain_t &onDataRead() + { return dataReadCallChain; } /** - * Set up a callback to be invoked to notify the user application that the - * GattServer instance is about to shut down (possibly as a result of a call - * to BLE::shutdown()). + * Set an event handler that monitors shutdown or reset of the GattServer. * - * @param[in] callback - * Event handler being registered. + * The event handler will be invoked when the GattServer instance is about + * to be shut down. This can result of a call to reset() or BLE::reset(). * - * @note It is possible to chain together multiple onShutdown callbacks - * (potentially from different modules of an application) to be notified - * before the GattServer is shut down. + * @param[in] callback Event handler being registered. * - * @note It is also possible to set up a callback into a member function of - * some object. + * @note It is possible to set up multiple shutdown event handlers. * - * @note It is possible to unregister a callback using onShutdown().detach(callback) + * @note It is possible to unregister a callback using + * onShutdown().detach(callback) */ - void onShutdown(const GattServerShutdownCallback_t& callback) { + void onShutdown(const GattServerShutdownCallback_t &callback) + { shutdownCallChain.add(callback); } /** - * Same as GattServer::onShutdown() but it allows the possibility to add an object - * reference and member function as handler for shutdown event - * callbacks. + * Set an event handler that monitors shutdown or reset of the GattServer. * - * @param[in] objPtr - * Pointer to the object of a class defining the member callback - * function (@p memberPtr). - * @param[in] memberPtr - * The member callback (within the context of an object) to be - * invoked. + * The event handler will be invoked when the GattServer instance is about + * to be shut down. This can result of a call to reset() or BLE::reset(). + * + * @param[in] objPtr Pointer to the instance that will be used to invoke the + * event handler (@p memberPtr). + * @param[in] memberPtr Event handler being registered. It is a member + * function. */ template - void onShutdown(T *objPtr, void (T::*memberPtr)(const GattServer *)) { + void onShutdown(T *objPtr, void (T::*memberPtr)(const GattServer *)) + { shutdownCallChain.add(objPtr, memberPtr); } /** - * @brief Provide access to the callchain of shutdown event callbacks. + * Access the callchain of shutdown event handlers. * * @return A reference to the shutdown event callbacks chain. * - * @note It is possible to register callbacks using onShutdown().add(callback). + * @note It is possible to register callbacks using + * onShutdown().add(callback). * - * @note It is possible to unregister callbacks using onShutdown().detach(callback). + * @note It is possible to unregister callbacks using + * onShutdown().detach(callback). */ - GattServerShutdownCallbackChain_t& onShutdown() { + GattServerShutdownCallbackChain_t& onShutdown() + { return shutdownCallChain; } /** - * Set up a callback for when notifications or indications are enabled for a - * characteristic on the local GATT server. + * Set up an event handler that monitors subscription to characteristic + * updates. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. */ - void onUpdatesEnabled(EventCallback_t callback) { + void onUpdatesEnabled(EventCallback_t callback) + { updatesEnabledCallback = callback; } /** - * Set up a callback for when notifications or indications are disabled for a - * characteristic on the local GATT server. + * Set up an event handler that monitors unsubscription from characteristic + * updates. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. */ - void onUpdatesDisabled(EventCallback_t callback) { + void onUpdatesDisabled(EventCallback_t callback) + { updatesDisabledCallback = callback; } /** - * Set up a callback for when the GATT server receives a response for an - * indication event sent previously. + * Set up an event handler that monitors notification acknowledgement. * - * @param[in] callback - * Event handler being registered. + * The event handler is called when a client send a confirmation that it has + * correctly received a notification from the server. + * + * @param[in] callback Event handler being registered. */ - void onConfirmationReceived(EventCallback_t callback) { + void onConfirmationReceived(EventCallback_t callback) + { confirmationReceivedCallback = callback; } @@ -544,42 +666,50 @@ public: protected: /** * Helper function that notifies all registered handlers of an occurrence - * of a data written event. This function is meant to be called from the - * BLE stack specific implementation when a data written event occurs. + * of a data written event. * - * @param[in] params - * The data written parameters passed to the registered - * handlers. + * @important Vendor implementation must invoke this function after one of + * the GattServer attribute has been written. + * + * @param[in] params The data written parameters passed to the registered + * handlers. */ - void handleDataWrittenEvent(const GattWriteCallbackParams *params) { + void handleDataWrittenEvent(const GattWriteCallbackParams *params) + { dataWrittenCallChain.call(params); } /** * Helper function that notifies all registered handlers of an occurrence - * of a data read event. This function is meant to be called from the - * BLE stack specific implementation when a data read event occurs. + * of a data read event. * - * @param[in] params - * The data read parameters passed to the registered - * handlers. + * @important Vendor implementation must invoke this function after one of + * the GattServer attribute has been read. + * + * @param[in] params The data read parameters passed to the registered + * handlers. */ - void handleDataReadEvent(const GattReadCallbackParams *params) { + void handleDataReadEvent(const GattReadCallbackParams *params) + { dataReadCallChain.call(params); } /** * Helper function that notifies the registered handler of an occurrence - * of updates enabled, updates disabled and confirmation received events. - * This function is meant to be called from the BLE stack specific - * implementation when any of these events occurs. + * of updates enabled, updates disabled or confirmation received events. * - * @param[in] type - * The type of event that occurred. - * @param[in] attributeHandle - * The handle of the attribute that was modified. + * @important Vendor implementation must invoke this function when a client + * subscribe to characteristic updates, unsubscribe from characteristic + * updates or a notification confirmation has been received. + * + * @param[in] type The type of event that occurred. + * @param[in] attributeHandle The handle of the attribute concerned by the + * event. */ - void handleEvent(GattServerEvents::gattEvent_e type, GattAttribute::Handle_t attributeHandle) { + void handleEvent( + GattServerEvents::gattEvent_e type, + GattAttribute::Handle_t attributeHandle + ) { switch (type) { case GattServerEvents::GATT_EVENT_UPDATES_ENABLED: if (updatesEnabledCallback) { @@ -603,31 +733,33 @@ protected: /** * Helper function that notifies all registered handlers of an occurrence - * of a data sent event. This function is meant to be called from the - * BLE stack specific implementation when a data sent event occurs. + * of a data sent event. * - * @param[in] count - * Number of packets sent. + * @important Vendor implementation must invoke this function after the + * emission of a notification or an indication. + * + * @param[in] count Number of packets sent. */ - void handleDataSentEvent(unsigned count) { + void handleDataSentEvent(unsigned count) + { dataSentCallChain.call(count); } public: /** - * Notify all registered onShutdown callbacks that the GattServer is - * about to be shut down and clear all GattServer state of the - * associated object. + * Shut down the GattServer instance. * - * This function is meant to be overridden in the platform-specific - * subclass. Nevertheless, the subclass only resets its - * state and not the data held in GattServer members. This is achieved - * by a call to GattServer::reset() from the subclass' reset() - * implementation. + * This function notifies all event handlers listening for shutdown events + * that the GattServer is about to be shut down; then it clear all + * GattServer state. + * + * @note This function is meant to be overridden in the platform-specific + * subclass. Overides must call the parent function before any cleanup. * * @return BLE_ERROR_NONE on success. */ - virtual ble_error_t reset(void) { + virtual ble_error_t reset(void) + { /* Notify that the instance is about to shutdown */ shutdownCallChain.call(this); shutdownCallChain.clear(); @@ -650,6 +782,7 @@ protected: * The total number of services added to the ATT table. */ uint8_t serviceCount; + /** * The total number of characteristics added to the ATT table. */ @@ -660,34 +793,40 @@ private: * Callchain containing all registered callback handlers for data sent * events. */ - DataSentCallbackChain_t dataSentCallChain; + DataSentCallbackChain_t dataSentCallChain; + /** * Callchain containing all registered callback handlers for data written * events. */ - DataWrittenCallbackChain_t dataWrittenCallChain; + DataWrittenCallbackChain_t dataWrittenCallChain; + /** * Callchain containing all registered callback handlers for data read * events. */ - DataReadCallbackChain_t dataReadCallChain; + DataReadCallbackChain_t dataReadCallChain; + /** * Callchain containing all registered callback handlers for shutdown * events. */ GattServerShutdownCallbackChain_t shutdownCallChain; + /** * The registered callback handler for updates enabled events. */ - EventCallback_t updatesEnabledCallback; + EventCallback_t updatesEnabledCallback; + /** * The registered callback handler for updates disabled events. */ - EventCallback_t updatesDisabledCallback; + EventCallback_t updatesDisabledCallback; + /** * The registered callback handler for confirmation received events. */ - EventCallback_t confirmationReceivedCallback; + EventCallback_t confirmationReceivedCallback; private: /* Disallow copy and assignment. */ @@ -701,4 +840,4 @@ private: * @} */ -#endif /* ifndef __GATT_SERVER_H__ */ +#endif /* ifndef MBED_GATT_SERVER_H__ */ diff --git a/features/FEATURE_BLE/ble/GattService.h b/features/FEATURE_BLE/ble/GattService.h index 4c340e0f06..18c44405a3 100644 --- a/features/FEATURE_BLE/ble/GattService.h +++ b/features/FEATURE_BLE/ble/GattService.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __GATT_SERVICE_H__ -#define __GATT_SERVICE_H__ +#ifndef MBED_GATT_SERVICE_H__ +#define MBED_GATT_SERVICE_H__ #include "UUID.h" #include "GattCharacteristic.h" @@ -29,49 +29,132 @@ * @{ */ +/** + * Representation of a GattServer service. + * + * A service is a cohesive collection of characteristics. It is identified by a + * UUID and starts at a specific handle of its GattServer. + */ class GattService { public: enum { - UUID_ALERT_NOTIFICATION_SERVICE = 0x1811, - UUID_BATTERY_SERVICE = 0x180F, - UUID_BLOOD_PRESSURE_SERVICE = 0x1810, - UUID_CURRENT_TIME_SERVICE = 0x1805, - UUID_CYCLING_SPEED_AND_CADENCE = 0x1816, - UUID_DEVICE_INFORMATION_SERVICE = 0x180A, - UUID_ENVIRONMENTAL_SERVICE = 0x181A, - UUID_GLUCOSE_SERVICE = 0x1808, - UUID_HEALTH_THERMOMETER_SERVICE = 0x1809, - UUID_HEART_RATE_SERVICE = 0x180D, + /** + * UUID of the Alert Notification service. + */ + UUID_ALERT_NOTIFICATION_SERVICE = 0x1811, + + /** + * UUID of the Battery service. + */ + UUID_BATTERY_SERVICE = 0x180F, + + /** + * UUID of the Blood Pressure service. + */ + UUID_BLOOD_PRESSURE_SERVICE = 0x1810, + + /** + * UUID of the Current Time service. + */ + UUID_CURRENT_TIME_SERVICE = 0x1805, + + /** + * UUID of the Cycling Speed and Carence (CSC) service. + */ + UUID_CYCLING_SPEED_AND_CADENCE = 0x1816, + + /** + * UUID of the Device Information Service (DIS). + */ + UUID_DEVICE_INFORMATION_SERVICE = 0x180A, + + /** + * UUID of the environmental service. + */ + UUID_ENVIRONMENTAL_SERVICE = 0x181A, + + /** + * UUID of the Glucose service. + */ + UUID_GLUCOSE_SERVICE = 0x1808, + + /** + * UUID of the health thermometer. + */ + UUID_HEALTH_THERMOMETER_SERVICE = 0x1809, + + /** + * UUID of the Heart Rate service. + */ + UUID_HEART_RATE_SERVICE = 0x180D, + + /** + * UUID of the Human Interface Device (HID) service. + */ UUID_HUMAN_INTERFACE_DEVICE_SERVICE = 0x1812, - UUID_IMMEDIATE_ALERT_SERVICE = 0x1802, - UUID_LINK_LOSS_SERVICE = 0x1803, - UUID_NEXT_DST_CHANGE_SERVICE = 0x1807, - UUID_PHONE_ALERT_STATUS_SERVICE = 0x180E, - UUID_REFERENCE_TIME_UPDATE_SERVICE = 0x1806, - UUID_RUNNING_SPEED_AND_CADENCE = 0x1814, - UUID_SCAN_PARAMETERS_SERVICE = 0x1813, - UUID_TX_POWER_SERVICE = 0x1804 + + /** + * UUID of the Immediate Alert service. + */ + UUID_IMMEDIATE_ALERT_SERVICE = 0x1802, + + /** + * UUID of the Link Loss service. + */ + UUID_LINK_LOSS_SERVICE = 0x1803, + + /** + * UUID of the Next DST change service. + */ + UUID_NEXT_DST_CHANGE_SERVICE = 0x1807, + + /** + * UUID of the Phone Alert Status service. + */ + UUID_PHONE_ALERT_STATUS_SERVICE = 0x180E, + + /** + * UUID of the Reference Time Update service. + */ + UUID_REFERENCE_TIME_UPDATE_SERVICE = 0x1806, + + /** + * UUID od the Running Speed and Cadence (RSC) service. + */ + UUID_RUNNING_SPEED_AND_CADENCE = 0x1814, + + /** + * UUID of the Scan Parameter service. + */ + UUID_SCAN_PARAMETERS_SERVICE = 0x1813, + + /** + * UUID of the TX power service. + */ + UUID_TX_POWER_SERVICE = 0x1804 }; public: /** - * @brief Creates a new GattService using the specified UUID and characteristics. + * Construct a GattService. * - * @note The UUID value must be unique and is normally >1. + * @param[in] uuid The UUID assigned to this service. + * @param[in] characteristics A pointer to the array of characteristics that + * belongs to the service. + * @param[in] numCharacteristics The number of characteristics. * - * @param[in] uuid - * The UUID to use for this service. - * @param[in] characteristics - * A pointer to an array of characteristics to be included within this service. - * @param[in] numCharacteristics - * The number of characteristics. + * @important The characteristics of the service must remain valid while the + * GattServer use the service. */ - GattService(const UUID &uuid, GattCharacteristic *characteristics[], unsigned numCharacteristics) : + GattService( + const UUID &uuid, + GattCharacteristic *characteristics[], + unsigned numCharacteristics + ) : _primaryServiceID(uuid), _characteristicCount(numCharacteristics), _characteristics(characteristics), _handle(0) { - /* empty */ } /** @@ -79,16 +162,18 @@ public: * * @return A reference to the service's UUID. */ - const UUID &getUUID(void) const { + const UUID &getUUID(void) const + { return _primaryServiceID; } /** - * Get handle of the service declaration attribute in the ATT table. + * Get the handle of the service declaration attribute in the ATT table. * * @return The service's handle. */ - uint16_t getHandle(void) const { + uint16_t getHandle(void) const + { return _handle; } @@ -97,29 +182,32 @@ public: * * @return The total number of characteristics within this service. */ - uint8_t getCharacteristicCount(void) const { + uint8_t getCharacteristicCount(void) const + { return _characteristicCount; } /** * Set the handle of the service declaration attribute in the ATT table. * - * @param[in] handle - * The service's handle. + * @important Application code must not use this API. + * + * @param[in] handle The service's handle. */ - void setHandle(uint16_t handle) { + void setHandle(uint16_t handle) + { _handle = handle; } /** * Get this service's characteristic at a specific index. * - * @param[in] index - * The index of the characteristic. + * @param[in] index The index of the characteristic. * * @return A pointer to the characteristic at index @p index. */ - GattCharacteristic *getCharacteristic(uint8_t index) { + GattCharacteristic *getCharacteristic(uint8_t index) + { if (index >= _characteristicCount) { return NULL; } @@ -131,22 +219,25 @@ private: /** * This service's UUID. */ - UUID _primaryServiceID; + UUID _primaryServiceID; + /** * Total number of characteristics within this service. */ - uint8_t _characteristicCount; + uint8_t _characteristicCount; + /** * An array with pointers to the characteristics added to this service. */ GattCharacteristic **_characteristics; + /** * Handle of the service declaration attribute in the ATT table. * * @note The underlying BLE stack generally assigns this handle when the - * service is added to the ATT table. + * service is added to the ATT table. */ - uint16_t _handle; + uint16_t _handle; }; /** @@ -155,5 +246,4 @@ private: * @} */ - -#endif /* ifndef __GATT_SERVICE_H__ */ +#endif /* ifndef MBED_GATT_SERVICE_H__ */