Hiroh Satoh / keyboard Featured

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   BLE_API mbed-dev nRF51822

HIDServiceBase.h@66:a7c6fbe45cf5, 2016-09-01 (annotated)

Committer:
cho45
Date:
Thu Sep 01 19:09:47 2016 +0000
Revision:
66:a7c6fbe45cf5
Parent:
59:2d6c0bff2151
Child:
75:351d7ffe81d1
?????????????????????????????????????????

Who changed what in which revision?

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