DeviceInformationService.h

00001 /* Preface:
00002    This is the HeartRateService from the mbed Microcontroller library. 
00003    Copied from https://github.com/ARMmbed/mbed-os/blob/master/features/FEATURE_BLE/ble/services/DeviceInformationService.h
00004    (2259e0d)
00005    
00006    The source has not been changed, but comments have been added to help clarify:
00007       Behavior, 
00008       C++ Syntax, and
00009       Design decisions
00010 
00011 Added comments are all in-line comments that start with:
00012   // COMMENT:       
00013       
00014 
00015 */
00016 
00017 /* mbed Microcontroller Library
00018  * Copyright (c) 2006-2013 ARM Limited
00019  *
00020  * Licensed under the Apache License, Version 2.0 (the "License");
00021  * you may not use this file except in compliance with the License.
00022  * You may obtain a copy of the License at
00023  *
00024  *     http://www.apache.org/licenses/LICENSE-2.0
00025  *
00026  * Unless required by applicable law or agreed to in writing, software
00027  * distributed under the License is distributed on an "AS IS" BASIS,
00028  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00029  * See the License for the specific language governing permissions and
00030  * limitations under the License.
00031  */
00032 
00033 #ifndef __BLE_DEVICE_INFORMATION_SERVICE_H__
00034 #define __BLE_DEVICE_INFORMATION_SERVICE_H__
00035 
00036 #include "ble/BLE.h"
00037 
00038 /**
00039 * @class DeviceInformationService
00040 * @brief BLE Device Information Service
00041 * Service: https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.device_information.xml
00042 * Manufacturer Name String Char: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.manufacturer_name_string.xml
00043 */
00044 class DeviceInformationService {
00045 public:
00046     /**
00047      * @brief Device Information Service Constructor: copies device-specific information
00048      * into the BLE stack.
00049      *
00050      * @param[in] _ble
00051      *                A reference to a BLE object for the underlying controller.
00052      * @param[in] manufacturersName
00053      *                The name of the manufacturer of the device.
00054      * @param[in] modelNumber
00055      *                The model number that is assigned by the device vendor.
00056      * @param[in] serialNumber
00057      *                The serial number for a particular instance of the device.
00058      * @param[in] hardwareRevision
00059      *                The hardware revision for the hardware within the device.
00060      * @param[in] firmwareRevision
00061      *                The device's firmware version.
00062      * @param[in] softwareRevision
00063      *                The device's software version.
00064      */
00065 // COMMENT: The following is a constructor. It uses "default" parameters so that most values don't have
00066 // COMMENT: to be provided.  The "BLE    &_ble" indicates a parameter being passed by reference. 
00067 // COMMENT: This is being done for efficiency. See: https://en.wikipedia.org/wiki/Reference_(C%2B%2B) for
00068 // COMMENT: details on references.
00069     DeviceInformationService(BLE        &_ble,
00070                              const char *manufacturersName = NULL,
00071                              const char *modelNumber       = NULL,
00072                              const char *serialNumber      = NULL,
00073                              const char *hardwareRevision  = NULL,
00074                              const char *firmwareRevision  = NULL,
00075                              const char *softwareRevision  = NULL) :
00076 // COMMENT: These are the "initialization list".  See: http://www.cprogramming.com/tutorial/initialization-lists-c++.html
00077         ble(_ble),
00078 // COMMENT: Each of the following initializes the "Characteristic" objects (the fields of this object)
00079 // COMMENT: Notice that the constructors are given a UUID, the data (via a pointer to it), the min/max length of the data, 
00080 // COMMENT: and the properties to use.
00081         manufacturersNameStringCharacteristic(GattCharacteristic::UUID_MANUFACTURER_NAME_STRING_CHAR,
00082                                               (uint8_t *)manufacturersName,
00083                                               (manufacturersName != NULL) ? strlen(manufacturersName) : 0, /* Min length */
00084                                               (manufacturersName != NULL) ? strlen(manufacturersName) : 0, /* Max length */
00085                                               GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
00086         modelNumberStringCharacteristic(GattCharacteristic::UUID_MODEL_NUMBER_STRING_CHAR,
00087                                         (uint8_t *)modelNumber,
00088                                         (modelNumber != NULL) ? strlen(modelNumber) : 0, /* Min length */
00089                                         (modelNumber != NULL) ? strlen(modelNumber) : 0, /* Max length */
00090                                         GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
00091         serialNumberStringCharacteristic(GattCharacteristic::UUID_SERIAL_NUMBER_STRING_CHAR,
00092                                          (uint8_t *)serialNumber,
00093                                          (serialNumber != NULL) ? strlen(serialNumber) : 0, /* Min length */
00094                                          (serialNumber != NULL) ? strlen(serialNumber) : 0, /* Max length */
00095                                          GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
00096         hardwareRevisionStringCharacteristic(GattCharacteristic::UUID_HARDWARE_REVISION_STRING_CHAR,
00097                                              (uint8_t *)hardwareRevision,
00098                                              (hardwareRevision != NULL) ? strlen(hardwareRevision) : 0, /* Min length */
00099                                              (hardwareRevision != NULL) ? strlen(hardwareRevision) : 0, /* Max length */
00100                                              GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
00101         firmwareRevisionStringCharacteristic(GattCharacteristic::UUID_FIRMWARE_REVISION_STRING_CHAR,
00102                                              (uint8_t *)firmwareRevision,
00103                                              (firmwareRevision != NULL) ? strlen(firmwareRevision) : 0, /* Min length */
00104                                              (firmwareRevision != NULL) ? strlen(firmwareRevision) : 0, /* Max length */
00105                                              GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
00106         softwareRevisionStringCharacteristic(GattCharacteristic::UUID_SOFTWARE_REVISION_STRING_CHAR,
00107                                              (uint8_t *)softwareRevision,
00108                                              (softwareRevision != NULL) ? strlen(softwareRevision) : 0, /* Min length */
00109                                              (softwareRevision != NULL) ? strlen(softwareRevision) : 0, /* Max length */
00110                                              GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ)
00111     {
00112 // COMMENT: The actual body of the function.  The Bluetooth specifications indicate that a device should only
00113 // COMMENT: have ONE device information service.  The above ensures that a second service couldn't be added.
00114 // COMMENT: (Devices can have many instances of some services if desired.  For example, a device could have 
00115 // COMMENT:  a service that can provide a single temperature.  It could have several instances of this service
00116 // COMMENT:  to support several thermometers that are connected to the same system device)
00117 // COMMENT: That being said, there's no sensible reason for a device to have more than one device information service. 
00118 // COMMENT: It should be a "singleton".
00119         static bool serviceAdded = false; /* We only add the information service once. */
00120 // COMMENT: static local variables in C++: a) are shared by all objects and b) continue to "exist" even when the
00121 // COMMENT: function isn't running.
00122         if (serviceAdded) {
00123             return;
00124         }
00125 // COMMENT: This builds the service table (an array of the individual characteristics)
00126 // COMMENT: Note the use of the "address-of" operation (&) to build the table. See: http://www.cplusplus.com/doc/tutorial/pointers/
00127         GattCharacteristic *charTable[] = {&manufacturersNameStringCharacteristic,
00128                                            &modelNumberStringCharacteristic,
00129                                            &serialNumberStringCharacteristic,
00130                                            &hardwareRevisionStringCharacteristic,
00131                                            &firmwareRevisionStringCharacteristic,
00132                                            &softwareRevisionStringCharacteristic};
00133 // COMMENT: The characteristics are added to a service object
00134         GattService         deviceInformationService(GattService::UUID_DEVICE_INFORMATION_SERVICE, charTable,
00135                                                      sizeof(charTable) / sizeof(GattCharacteristic *));
00136 // COMMENT: And the service object is added to the server.
00137         ble.addService(deviceInformationService);
00138         serviceAdded = true;
00139     }
00140 
00141 protected:
00142     /**
00143      * A reference to the BLE instance object to which the services and
00144      * characteristics will be added.
00145      */
00146     BLE                &ble;
00147     /**
00148      * BLE characterising to allow BLE peers access to the manufacturer's name.
00149      */
00150     GattCharacteristic  manufacturersNameStringCharacteristic;
00151     /**
00152      * BLE characterising to allow BLE peers access to the model number.
00153      */
00154     GattCharacteristic  modelNumberStringCharacteristic;
00155     /**
00156      * BLE characterising to allow BLE peers access to the serial number.
00157      */
00158     GattCharacteristic  serialNumberStringCharacteristic;
00159     /**
00160      * BLE characterising to allow BLE peers access to the hardware revision string.
00161      */
00162 // COMMENT: Below are the fields for the individual characteristics of the service. 
00163     GattCharacteristic  hardwareRevisionStringCharacteristic;
00164     /**
00165      * BLE characterising to allow BLE peers access to the firmware revision string.
00166      */
00167     GattCharacteristic  firmwareRevisionStringCharacteristic;
00168     /**
00169      * BLE characterising to allow BLE peers access to the software revision string.
00170      */
00171     GattCharacteristic  softwareRevisionStringCharacteristic;
00172 };
00173 
00174 #endif /* #ifndef __BLE_DEVICE_INFORMATION_SERVICE_H__*/