BitBoard / bit_board_James

back up of work during May 2019

Dependencies:   microbit

BLE_HID/HIDServiceBase.h@1:c840c2b6f490, 2019-05-31 (annotated)

Committer:
xx316
Date:
Fri May 31 20:53:51 2019 +0000
Revision:
1:c840c2b6f490
This is the program for bit_board, an accessory developed by a group of Imperial EEE students for MicroBit. This is the first commit to backup the work in May 2019.

Who changed what in which revision?

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