Skip to content

Commit cc478b3

Browse files
paul-szczepanek-armpaul-szczepanek-arm
committed
add deprecation warning
1 parent c6d2ca1 commit cc478b3

File tree

6 files changed

+918
-0
lines changed

6 files changed

+918
-0
lines changed

‎connectivity/FEATURE_BLE/include/ble/services/BatteryService.h

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
/* mbed Microcontroller Library
2+
* Copyright (c) 2006-2020 ARM Limited
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
#warning "These services are deprecated and will be removed. Please see services.md for details about replacement services."
20+
21+
#ifndef MBED_BLE_BATTERY_SERVICE_H__
22+
#define MBED_BLE_BATTERY_SERVICE_H__
23+
24+
#if BLE_FEATURE_GATT_SERVER
25+
26+
#include "platform/mbed_assert.h"
27+
28+
#include "ble/BLE.h"
29+
#include "ble/Gap.h"
30+
#include "ble/GattServer.h"
31+
32+
/**
33+
* BLE Battery service.
34+
*
35+
* @par purpose
36+
*
37+
* The battery service exposes the charge level of the battery of the device.
38+
* This information is exposed as a percentage from 0% to 100%; a value of 0%
39+
* represents a fully discharged battery, and a value of 100% represents a
40+
* fully charged battery.
41+
*
42+
* Clients can read the current charge level and subscribe to server initiated
43+
* updates of the charge level. The server delivers these updates to the subscribed
44+
* client in a notification packet.
45+
*
46+
* The subscription mechanism is useful to save power; it avoids unecessary data
47+
* traffic between the client and the server, which may be induced by polling the
48+
* battery level characteristic value.
49+
*
50+
* @par usage
51+
*
52+
* When this class is instantiated, it adds a battery service in the GattServer.
53+
*
54+
* The application code can use the function updateBatteryLevel() to update the
55+
* charge level that the service exposes and to notify the subscribed client that the
56+
* value changed.
57+
*
58+
* @note You can find specification of the battery service here:
59+
* https://www.bluetooth.com/specifications/gatt
60+
*
61+
* @attention Multiple instances of this battery service are not supported.
62+
*/
63+
class BatteryService {
64+
public:
65+
/**
66+
* Instantiate a battery service.
67+
*
68+
* The construction of a BatteryService adds a GATT battery service in @p
69+
* _ble GattServer and sets the initial charge level of the battery to @p
70+
* level.
71+
*
72+
* @param[in] _ble BLE device which will host the battery service.
73+
* @param[in] level Initial charge level of the battery. It is a percentage
74+
* where 0% means that the battery is fully discharged and 100% means that
75+
* the battery is fully charged.
76+
*/
77+
BatteryService(BLE &_ble, uint8_t level = 100) :
78+
ble(_ble),
79+
batteryLevel(level),
80+
batteryLevelCharacteristic(
81+
GattCharacteristic::UUID_BATTERY_LEVEL_CHAR,
82+
&batteryLevel,
83+
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
84+
)
85+
{
86+
MBED_ASSERT(level <= 100);
87+
GattCharacteristic *charTable[] = { &batteryLevelCharacteristic };
88+
GattService batteryService(
89+
GattService::UUID_BATTERY_SERVICE,
90+
charTable,
91+
sizeof(charTable) / sizeof(charTable[0])
92+
);
93+
94+
ble.gattServer().addService(batteryService);
95+
}
96+
97+
/**
98+
* Update the battery charge level that the service exposes.
99+
*
100+
* The server sends a notification of the new value to clients that have
101+
* subscribed to the battery level characteristic updates, and clients
102+
* reading the charge level after the update obtain the updated value.
103+
*
104+
* @param newLevel Charge level of the battery. It is a percentage of the
105+
* remaining charge between 0% and 100%.
106+
*
107+
* @attention This function must be called in the execution context of the
108+
* BLE stack.
109+
*/
110+
void updateBatteryLevel(uint8_t newLevel)
111+
{
112+
MBED_ASSERT(newLevel <= 100);
113+
batteryLevel = newLevel;
114+
ble.gattServer().write(
115+
batteryLevelCharacteristic.getValueHandle(),
116+
&batteryLevel,
117+
1
118+
);
119+
}
120+
121+
protected:
122+
/**
123+
* Reference to the underlying BLE instance that this object is attached to.
124+
*
125+
* The services and characteristics are registered in the GattServer of
126+
* this BLE instance.
127+
*/
128+
BLE &ble;
129+
130+
/**
131+
* The current battery level represented as an integer from 0% to 100%.
132+
*/
133+
uint8_t batteryLevel;
134+
135+
/**
136+
* The GATT characteristic, which exposes the charge level.
137+
*/
138+
ReadOnlyGattCharacteristic<uint8_t> batteryLevelCharacteristic;
139+
};
140+
141+
#endif // BLE_FEATURE_GATT_SERVER
142+
143+
#endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/

‎connectivity/FEATURE_BLE/include/ble/services/DeviceInformationService.h

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
/* mbed Microcontroller Library
2+
* Copyright (c) 2006-2020 ARM Limited
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
#warning "These services are deprecated and will be removed. Please see services.md for details about replacement services."
20+
21+
#ifndef __BLE_DEVICE_INFORMATION_SERVICE_H__
22+
#define __BLE_DEVICE_INFORMATION_SERVICE_H__
23+
24+
#include "ble/BLE.h"
25+
#include "ble/Gap.h"
26+
#include "ble/GattServer.h"
27+
28+
#if BLE_FEATURE_GATT_SERVER
29+
30+
/**
31+
* @class DeviceInformationService
32+
* @brief BLE Device Information Service
33+
* Service: https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.device_information.xml
34+
* Manufacturer Name String Char: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.manufacturer_name_string.xml
35+
*/
36+
class DeviceInformationService {
37+
public:
38+
/**
39+
* @brief Device Information Service Constructor: copies device-specific information
40+
* into the BLE stack.
41+
*
42+
* @param[in] _ble
43+
* A reference to a BLE object for the underlying controller.
44+
* @param[in] manufacturersName
45+
* The name of the manufacturer of the device.
46+
* @param[in] modelNumber
47+
* The model number that is assigned by the device vendor.
48+
* @param[in] serialNumber
49+
* The serial number for a particular instance of the device.
50+
* @param[in] hardwareRevision
51+
* The hardware revision for the hardware within the device.
52+
* @param[in] firmwareRevision
53+
* The device's firmware version.
54+
* @param[in] softwareRevision
55+
* The device's software version.
56+
*/
57+
DeviceInformationService(BLE &_ble,
58+
const char *manufacturersName = nullptr,
59+
const char *modelNumber = nullptr,
60+
const char *serialNumber = nullptr,
61+
const char *hardwareRevision = nullptr,
62+
const char *firmwareRevision = nullptr,
63+
const char *softwareRevision = nullptr) :
64+
ble(_ble),
65+
manufacturersNameStringCharacteristic(GattCharacteristic::UUID_MANUFACTURER_NAME_STRING_CHAR,
66+
(uint8_t *)manufacturersName,
67+
(manufacturersName != nullptr) ? strlen(manufacturersName) : 0, /* Min length */
68+
(manufacturersName != nullptr) ? strlen(manufacturersName) : 0, /* Max length */
69+
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
70+
modelNumberStringCharacteristic(GattCharacteristic::UUID_MODEL_NUMBER_STRING_CHAR,
71+
(uint8_t *)modelNumber,
72+
(modelNumber != nullptr) ? strlen(modelNumber) : 0, /* Min length */
73+
(modelNumber != nullptr) ? strlen(modelNumber) : 0, /* Max length */
74+
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
75+
serialNumberStringCharacteristic(GattCharacteristic::UUID_SERIAL_NUMBER_STRING_CHAR,
76+
(uint8_t *)serialNumber,
77+
(serialNumber != nullptr) ? strlen(serialNumber) : 0, /* Min length */
78+
(serialNumber != nullptr) ? strlen(serialNumber) : 0, /* Max length */
79+
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
80+
hardwareRevisionStringCharacteristic(GattCharacteristic::UUID_HARDWARE_REVISION_STRING_CHAR,
81+
(uint8_t *)hardwareRevision,
82+
(hardwareRevision != nullptr) ? strlen(hardwareRevision) : 0, /* Min length */
83+
(hardwareRevision != nullptr) ? strlen(hardwareRevision) : 0, /* Max length */
84+
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
85+
firmwareRevisionStringCharacteristic(GattCharacteristic::UUID_FIRMWARE_REVISION_STRING_CHAR,
86+
(uint8_t *)firmwareRevision,
87+
(firmwareRevision != nullptr) ? strlen(firmwareRevision) : 0, /* Min length */
88+
(firmwareRevision != nullptr) ? strlen(firmwareRevision) : 0, /* Max length */
89+
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
90+
softwareRevisionStringCharacteristic(GattCharacteristic::UUID_SOFTWARE_REVISION_STRING_CHAR,
91+
(uint8_t *)softwareRevision,
92+
(softwareRevision != nullptr) ? strlen(softwareRevision) : 0, /* Min length */
93+
(softwareRevision != nullptr) ? strlen(softwareRevision) : 0, /* Max length */
94+
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ)
95+
{
96+
static bool serviceAdded = false; /* We only add the information service once. */
97+
if (serviceAdded) {
98+
return;
99+
}
100+
101+
GattCharacteristic *charTable[] = {&manufacturersNameStringCharacteristic,
102+
&modelNumberStringCharacteristic,
103+
&serialNumberStringCharacteristic,
104+
&hardwareRevisionStringCharacteristic,
105+
&firmwareRevisionStringCharacteristic,
106+
&softwareRevisionStringCharacteristic};
107+
GattService deviceInformationService(GattService::UUID_DEVICE_INFORMATION_SERVICE, charTable,
108+
sizeof(charTable) / sizeof(charTable[0]));
109+
110+
ble.gattServer().addService(deviceInformationService);
111+
serviceAdded = true;
112+
}
113+
114+
protected:
115+
/**
116+
* A reference to the BLE instance object to which the services and
117+
* characteristics will be added.
118+
*/
119+
BLE &ble;
120+
/**
121+
* BLE characterising to allow BLE peers access to the manufacturer's name.
122+
*/
123+
GattCharacteristic manufacturersNameStringCharacteristic;
124+
/**
125+
* BLE characterising to allow BLE peers access to the model number.
126+
*/
127+
GattCharacteristic modelNumberStringCharacteristic;
128+
/**
129+
* BLE characterising to allow BLE peers access to the serial number.
130+
*/
131+
GattCharacteristic serialNumberStringCharacteristic;
132+
/**
133+
* BLE characterising to allow BLE peers access to the hardware revision string.
134+
*/
135+
GattCharacteristic hardwareRevisionStringCharacteristic;
136+
/**
137+
* BLE characterising to allow BLE peers access to the firmware revision string.
138+
*/
139+
GattCharacteristic firmwareRevisionStringCharacteristic;
140+
/**
141+
* BLE characterising to allow BLE peers access to the software revision string.
142+
*/
143+
GattCharacteristic softwareRevisionStringCharacteristic;
144+
};
145+
146+
#endif // BLE_FEATURE_GATT_SERVER
147+
148+
#endif /* #ifndef __BLE_DEVICE_INFORMATION_SERVICE_H__*/

0 commit comments

Comments
 (0)