Renato Grottesi / microbit-dal

MicroBit as BLE gamepad

Dependencies:   BLE_API mbed-dev-bin nRF51822

Dependents:   microbit

Fork of microbit-dal by Lancaster University

BLE_HID/HIDServiceBase.h@75:df904445f561, 2017-01-30 (annotated)

Committer:
rengro01
Date:
Mon Jan 30 08:29:06 2017 +0000
Revision:
75:df904445f561
Parent:
74:1b9850e39cd1 
MicroBit as BLE gamepad

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rengro01 74:1b9850e39cd1 1 /* mbed Microcontroller Library
rengro01 74:1b9850e39cd1 2 * Copyright (c) 2015 ARM Limited
rengro01 74:1b9850e39cd1 3 *
rengro01 74:1b9850e39cd1 4 * Licensed under the Apache License, Version 2.0 (the "License");
rengro01 74:1b9850e39cd1 5 * you may not use this file except in compliance with the License.
rengro01 74:1b9850e39cd1 6 * You may obtain a copy of the License at
rengro01 74:1b9850e39cd1 7 *
rengro01 74:1b9850e39cd1 8 * http://www.apache.org/licenses/LICENSE-2.0
rengro01 74:1b9850e39cd1 9 *
rengro01 74:1b9850e39cd1 10 * Unless required by applicable law or agreed to in writing, software
rengro01 74:1b9850e39cd1 11 * distributed under the License is distributed on an "AS IS" BASIS,
rengro01 74:1b9850e39cd1 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rengro01 74:1b9850e39cd1 13 * See the License for the specific language governing permissions and
rengro01 74:1b9850e39cd1 14 * limitations under the License.
rengro01 74:1b9850e39cd1 15 */
rengro01 74:1b9850e39cd1 16
rengro01 74:1b9850e39cd1 17 #ifndef HID_SERVICE_BASE_H_
rengro01 74:1b9850e39cd1 18 #define HID_SERVICE_BASE_H_
rengro01 74:1b9850e39cd1 19
rengro01 74:1b9850e39cd1 20 #include "mbed.h"
rengro01 74:1b9850e39cd1 21
rengro01 74:1b9850e39cd1 22 #include "ble/BLE.h"
rengro01 74:1b9850e39cd1 23 #include "HID_types.h"
rengro01 74:1b9850e39cd1 24
rengro01 74:1b9850e39cd1 25 #define BLE_UUID_DESCRIPTOR_REPORT_REFERENCE 0x2908
rengro01 74:1b9850e39cd1 26
rengro01 74:1b9850e39cd1 27 typedef const uint8_t report_map_t[];
rengro01 74:1b9850e39cd1 28 typedef const uint8_t * report_t;
rengro01 74:1b9850e39cd1 29
rengro01 74:1b9850e39cd1 30 typedef struct {
rengro01 74:1b9850e39cd1 31 uint16_t bcdHID;
rengro01 74:1b9850e39cd1 32 uint8_t bCountryCode;
rengro01 74:1b9850e39cd1 33 uint8_t flags;
rengro01 74:1b9850e39cd1 34 } HID_information_t;
rengro01 74:1b9850e39cd1 35
rengro01 74:1b9850e39cd1 36 enum ReportType {
rengro01 74:1b9850e39cd1 37 INPUT_REPORT = 0x1,
rengro01 74:1b9850e39cd1 38 OUTPUT_REPORT = 0x2,
rengro01 74:1b9850e39cd1 39 FEATURE_REPORT = 0x3,
rengro01 74:1b9850e39cd1 40 };
rengro01 74:1b9850e39cd1 41
rengro01 74:1b9850e39cd1 42 enum ProtocolMode {
rengro01 74:1b9850e39cd1 43 BOOT_PROTOCOL = 0x0,
rengro01 74:1b9850e39cd1 44 REPORT_PROTOCOL = 0x1,
rengro01 74:1b9850e39cd1 45 };
rengro01 74:1b9850e39cd1 46
rengro01 74:1b9850e39cd1 47 typedef struct {
rengro01 74:1b9850e39cd1 48 uint8_t ID;
rengro01 74:1b9850e39cd1 49 uint8_t type;
rengro01 74:1b9850e39cd1 50 } report_reference_t;
rengro01 74:1b9850e39cd1 51
rengro01 74:1b9850e39cd1 52
rengro01 74:1b9850e39cd1 53 class HIDServiceBase {
rengro01 74:1b9850e39cd1 54 public:
rengro01 74:1b9850e39cd1 55 /**
rengro01 74:1b9850e39cd1 56 * Constructor
rengro01 74:1b9850e39cd1 57 *
rengro01 74:1b9850e39cd1 58 * @param _ble
rengro01 74:1b9850e39cd1 59 * BLE object to add this service to
rengro01 74:1b9850e39cd1 60 * @param reportMap
rengro01 74:1b9850e39cd1 61 * Byte array representing the input/output report formats. In USB HID jargon, it
rengro01 74:1b9850e39cd1 62 * is called "HID report descriptor".
rengro01 74:1b9850e39cd1 63 * @param reportMapLength
rengro01 74:1b9850e39cd1 64 * Size of the reportMap array
rengro01 74:1b9850e39cd1 65 * @param outputReportLength
rengro01 74:1b9850e39cd1 66 * Maximum length of a sent report (up to 64 bytes) (default: 64 bytes)
rengro01 74:1b9850e39cd1 67 * @param inputReportLength
rengro01 74:1b9850e39cd1 68 * Maximum length of a received report (up to 64 bytes) (default: 64 bytes)
rengro01 74:1b9850e39cd1 69 * @param inputReportTickerDelay
rengro01 74:1b9850e39cd1 70 * Delay between input report notifications, in ms. Acceptable values depend directly on
rengro01 74:1b9850e39cd1 71 * GAP's connInterval parameter, so it shouldn't be less than 12ms
rengro01 74:1b9850e39cd1 72 * Preferred GAP connection interval is set after this value, in order to send
rengro01 74:1b9850e39cd1 73 * notifications as quick as possible: minimum connection interval will be set to
rengro01 74:1b9850e39cd1 74 * (inputReportTickerDelay / 2)
rengro01 74:1b9850e39cd1 75 */
rengro01 74:1b9850e39cd1 76 HIDServiceBase(BLE &_ble,
rengro01 74:1b9850e39cd1 77 report_map_t reportMap,
rengro01 74:1b9850e39cd1 78 uint8_t reportMapLength,
rengro01 74:1b9850e39cd1 79 report_t inputReport,
rengro01 74:1b9850e39cd1 80 report_t outputReport,
rengro01 74:1b9850e39cd1 81 report_t featureReport,
rengro01 74:1b9850e39cd1 82 uint8_t inputReportLength = 0,
rengro01 74:1b9850e39cd1 83 uint8_t outputReportLength = 0,
rengro01 74:1b9850e39cd1 84 uint8_t featureReportLength = 0,
rengro01 74:1b9850e39cd1 85 uint8_t inputReportTickerDelay = 50);
rengro01 74:1b9850e39cd1 86
rengro01 74:1b9850e39cd1 87 /**
rengro01 74:1b9850e39cd1 88 * Send Report
rengro01 74:1b9850e39cd1 89 *
rengro01 74:1b9850e39cd1 90 * @param report Report to send. Must be of size @ref inputReportLength
rengro01 74:1b9850e39cd1 91 * @return The write status
rengro01 74:1b9850e39cd1 92 *
rengro01 74:1b9850e39cd1 93 * @note Don't call send() directly for multiple reports! Use reportTicker for that, in order
rengro01 74:1b9850e39cd1 94 * to avoid overloading the BLE stack, and let it handle events between each report.
rengro01 74:1b9850e39cd1 95 */
rengro01 74:1b9850e39cd1 96 virtual ble_error_t send(const report_t report);
rengro01 74:1b9850e39cd1 97
rengro01 74:1b9850e39cd1 98 /**
rengro01 74:1b9850e39cd1 99 * Read Report
rengro01 74:1b9850e39cd1 100 *
rengro01 74:1b9850e39cd1 101 * @param report Report to fill. Must be of size @ref outputReportLength
rengro01 74:1b9850e39cd1 102 * @return The read status
rengro01 74:1b9850e39cd1 103 */
rengro01 74:1b9850e39cd1 104 virtual ble_error_t read(report_t report);
rengro01 74:1b9850e39cd1 105
rengro01 74:1b9850e39cd1 106 virtual void onConnection(const Gap::ConnectionCallbackParams_t *params);
rengro01 74:1b9850e39cd1 107 virtual void onDisconnection(const Gap::DisconnectionCallbackParams_t *params);
rengro01 74:1b9850e39cd1 108
rengro01 74:1b9850e39cd1 109 virtual bool isConnected(void)
rengro01 74:1b9850e39cd1 110 {
rengro01 74:1b9850e39cd1 111 return connected;
rengro01 74:1b9850e39cd1 112 }
rengro01 74:1b9850e39cd1 113
rengro01 74:1b9850e39cd1 114 protected:
rengro01 74:1b9850e39cd1 115 /**
rengro01 74:1b9850e39cd1 116 * Called by BLE API when data has been successfully sent.
rengro01 74:1b9850e39cd1 117 *
rengro01 74:1b9850e39cd1 118 * @param count Number of reports sent
rengro01 74:1b9850e39cd1 119 *
rengro01 74:1b9850e39cd1 120 * @note Subclasses can override this to avoid starting the report ticker when there is nothing
rengro01 74:1b9850e39cd1 121 * to send
rengro01 74:1b9850e39cd1 122 */
rengro01 74:1b9850e39cd1 123 virtual void onDataSent(unsigned count);
rengro01 74:1b9850e39cd1 124
rengro01 74:1b9850e39cd1 125 /**
rengro01 74:1b9850e39cd1 126 * Start the ticker that sends input reports at regular interval
rengro01 74:1b9850e39cd1 127 *
rengro01 74:1b9850e39cd1 128 * @note reportTickerIsActive describes the state of the ticker and can be used by HIDS
rengro01 74:1b9850e39cd1 129 * implementations.
rengro01 74:1b9850e39cd1 130 */
rengro01 74:1b9850e39cd1 131 virtual void startReportTicker(void);
rengro01 74:1b9850e39cd1 132
rengro01 74:1b9850e39cd1 133 /**
rengro01 74:1b9850e39cd1 134 * Stop the input report ticker
rengro01 74:1b9850e39cd1 135 */
rengro01 74:1b9850e39cd1 136 virtual void stopReportTicker(void);
rengro01 74:1b9850e39cd1 137
rengro01 74:1b9850e39cd1 138 /**
rengro01 74:1b9850e39cd1 139 * Called by input report ticker at regular interval (reportTickerDelay). This must be
rengro01 74:1b9850e39cd1 140 * overriden by HIDS implementations to call the @ref send() with a report, if necessary.
rengro01 74:1b9850e39cd1 141 */
rengro01 74:1b9850e39cd1 142 virtual void sendCallback(void) = 0;
rengro01 74:1b9850e39cd1 143
rengro01 74:1b9850e39cd1 144 /**
rengro01 74:1b9850e39cd1 145 * Create the Gatt descriptor for a report characteristic
rengro01 74:1b9850e39cd1 146 */
rengro01 74:1b9850e39cd1 147 GattAttribute** inputReportDescriptors();
rengro01 74:1b9850e39cd1 148 GattAttribute** outputReportDescriptors();
rengro01 74:1b9850e39cd1 149 GattAttribute** featureReportDescriptors();
rengro01 74:1b9850e39cd1 150
rengro01 74:1b9850e39cd1 151 /**
rengro01 74:1b9850e39cd1 152 * Create the HID information structure
rengro01 74:1b9850e39cd1 153 */
rengro01 74:1b9850e39cd1 154 HID_information_t* HIDInformation();
rengro01 74:1b9850e39cd1 155
rengro01 74:1b9850e39cd1 156 protected:
rengro01 74:1b9850e39cd1 157 BLE &ble;
rengro01 74:1b9850e39cd1 158 bool connected;
rengro01 74:1b9850e39cd1 159
rengro01 74:1b9850e39cd1 160 int reportMapLength;
rengro01 74:1b9850e39cd1 161
rengro01 74:1b9850e39cd1 162 report_t inputReport;
rengro01 74:1b9850e39cd1 163 report_t outputReport;
rengro01 74:1b9850e39cd1 164 report_t featureReport;
rengro01 74:1b9850e39cd1 165
rengro01 74:1b9850e39cd1 166 uint8_t inputReportLength;
rengro01 74:1b9850e39cd1 167 uint8_t outputReportLength;
rengro01 74:1b9850e39cd1 168 uint8_t featureReportLength;
rengro01 74:1b9850e39cd1 169
rengro01 74:1b9850e39cd1 170 uint8_t controlPointCommand;
rengro01 74:1b9850e39cd1 171 uint8_t protocolMode;
rengro01 74:1b9850e39cd1 172
rengro01 74:1b9850e39cd1 173 report_reference_t inputReportReferenceData;
rengro01 74:1b9850e39cd1 174 report_reference_t outputReportReferenceData;
rengro01 74:1b9850e39cd1 175 report_reference_t featureReportReferenceData;
rengro01 74:1b9850e39cd1 176
rengro01 74:1b9850e39cd1 177 GattAttribute inputReportReferenceDescriptor;
rengro01 74:1b9850e39cd1 178 GattAttribute outputReportReferenceDescriptor;
rengro01 74:1b9850e39cd1 179 GattAttribute featureReportReferenceDescriptor;
rengro01 74:1b9850e39cd1 180
rengro01 74:1b9850e39cd1 181 // Optional gatt characteristics:
rengro01 74:1b9850e39cd1 182 GattCharacteristic protocolModeCharacteristic;
rengro01 74:1b9850e39cd1 183
rengro01 74:1b9850e39cd1 184 // Report characteristics (each sort of optional)
rengro01 74:1b9850e39cd1 185 GattCharacteristic inputReportCharacteristic;
rengro01 74:1b9850e39cd1 186 GattCharacteristic outputReportCharacteristic;
rengro01 74:1b9850e39cd1 187 GattCharacteristic featureReportCharacteristic;
rengro01 74:1b9850e39cd1 188
rengro01 74:1b9850e39cd1 189 // Required gatt characteristics: Report Map, Information, Control Point
rengro01 74:1b9850e39cd1 190 GattCharacteristic reportMapCharacteristic;
rengro01 74:1b9850e39cd1 191 ReadOnlyGattCharacteristic<HID_information_t> HIDInformationCharacteristic;
rengro01 74:1b9850e39cd1 192 GattCharacteristic HIDControlPointCharacteristic;
rengro01 74:1b9850e39cd1 193
rengro01 74:1b9850e39cd1 194 Ticker reportTicker;
rengro01 74:1b9850e39cd1 195 uint32_t reportTickerDelay;
rengro01 74:1b9850e39cd1 196 bool reportTickerIsActive;
rengro01 74:1b9850e39cd1 197 };
rengro01 74:1b9850e39cd1 198
rengro01 74:1b9850e39cd1 199 #endif /* !HID_SERVICE_BASE_H_ */
rengro01 74:1b9850e39cd1 200