HIDServiceBase.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef HID_SERVICE_BASE_H_
00018 #define HID_SERVICE_BASE_H_
00019 
00020 #include "mbed.h"
00021 
00022 #include "ble/BLE.h"
00023 #include "HID_types.h"
00024 
00025 #define BLE_UUID_DESCRIPTOR_REPORT_REFERENCE 0x2908
00026 
00027 typedef const uint8_t report_map_t[];
00028 typedef const uint8_t * report_t;
00029 
00030 typedef struct {
00031     uint16_t bcdHID;
00032     uint8_t  bCountryCode;
00033     uint8_t  flags;
00034 } HID_information_t;
00035 
00036 enum ReportType {
00037     INPUT_REPORT    = 0x1,
00038     OUTPUT_REPORT   = 0x2,
00039     FEATURE_REPORT  = 0x3,
00040 };
00041 
00042 enum ProtocolMode {
00043     BOOT_PROTOCOL   = 0x0,
00044     REPORT_PROTOCOL = 0x1,
00045 };
00046 
00047 typedef struct {
00048     uint8_t ID;
00049     uint8_t type;
00050 } report_reference_t;
00051 
00052 
00053 class HIDServiceBase {
00054 public:
00055     /**
00056      *  Constructor
00057      *
00058      *  @param _ble
00059      *         BLE object to add this service to
00060      *  @param reportMap
00061      *         Byte array representing the input/output report formats. In USB HID jargon, it
00062      *         is called "HID report descriptor".
00063      *  @param reportMapLength 
00064      *         Size of the reportMap array
00065      *  @param outputReportLength
00066      *         Maximum length of a sent report (up to 64 bytes) (default: 64 bytes)
00067      *  @param inputReportLength
00068      *         Maximum length of a received report (up to 64 bytes) (default: 64 bytes)
00069      *  @param inputReportTickerDelay
00070      *         Delay between input report notifications, in ms. Acceptable values depend directly on
00071      *         GAP's connInterval parameter, so it shouldn't be less than 12ms
00072      *         Preferred GAP connection interval is set after this value, in order to send
00073      *         notifications as quick as possible: minimum connection interval will be set to
00074      *         (inputReportTickerDelay / 2)
00075      */
00076     HIDServiceBase(BLE &_ble,
00077                    report_map_t reportMap,
00078                    uint8_t reportMapLength,
00079                    report_t inputReport,
00080                    report_t outputReport,
00081                    report_t featureReport,
00082                    uint8_t inputReportLength = 0,
00083                    uint8_t outputReportLength = 0,
00084                    uint8_t featureReportLength = 0,
00085                    uint8_t inputReportTickerDelay = 50);
00086 
00087     /**
00088      *  Send Report
00089      *
00090      *  @param report   Report to send. Must be of size @ref inputReportLength
00091      *  @return         The write status
00092      *
00093      *  @note Don't call send() directly for multiple reports! Use reportTicker for that, in order
00094      *  to avoid overloading the BLE stack, and let it handle events between each report.
00095      */
00096     virtual ble_error_t send(const report_t report);
00097 
00098     /**
00099      *  Read Report
00100      *
00101      *  @param report   Report to fill. Must be of size @ref outputReportLength
00102      *  @return         The read status
00103      */
00104     virtual ble_error_t read(report_t report);
00105 
00106     virtual void onConnection(const Gap::ConnectionCallbackParams_t *params);
00107     virtual void onDisconnection(const Gap::DisconnectionCallbackParams_t *params);
00108 
00109     virtual bool isConnected(void)
00110     {
00111         return connected;
00112     }
00113 
00114 protected:
00115     /**
00116      * Called by BLE API when data has been successfully sent.
00117      *
00118      * @param count     Number of reports sent
00119      *
00120      * @note Subclasses can override this to avoid starting the report ticker when there is nothing
00121      * to send
00122      */
00123     virtual void onDataSent(unsigned count);
00124 
00125     /**
00126      * Start the ticker that sends input reports at regular interval
00127      *
00128      * @note reportTickerIsActive describes the state of the ticker and can be used by HIDS
00129      * implementations.
00130      */
00131     virtual void startReportTicker(void);
00132 
00133     /**
00134      * Stop the input report ticker
00135      */
00136     virtual void stopReportTicker(void);
00137 
00138     /**
00139      * Called by input report ticker at regular interval (reportTickerDelay). This must be
00140      * overriden by HIDS implementations to call the @ref send() with a report, if necessary.
00141      */
00142     virtual void sendCallback(void) = 0;
00143 
00144     /**
00145      * Create the Gatt descriptor for a report characteristic
00146      */
00147     GattAttribute** inputReportDescriptors();
00148     GattAttribute** outputReportDescriptors();
00149     GattAttribute** featureReportDescriptors();
00150 
00151     /**
00152      * Create the HID information structure
00153      */
00154     HID_information_t* HIDInformation();
00155 
00156 protected:
00157     BLE &ble;
00158     bool connected;
00159 
00160     int reportMapLength;
00161 
00162     report_t inputReport;
00163     report_t outputReport;
00164     report_t featureReport;
00165 
00166     uint8_t inputReportLength;
00167     uint8_t outputReportLength;
00168     uint8_t featureReportLength;
00169 
00170     uint8_t controlPointCommand;
00171     uint8_t protocolMode;
00172 
00173     report_reference_t inputReportReferenceData;
00174     report_reference_t outputReportReferenceData;
00175     report_reference_t featureReportReferenceData;
00176 
00177     GattAttribute inputReportReferenceDescriptor;
00178     GattAttribute outputReportReferenceDescriptor;
00179     GattAttribute featureReportReferenceDescriptor;
00180 
00181     // Optional gatt characteristics:
00182     GattCharacteristic protocolModeCharacteristic;
00183 
00184     // Report characteristics (each sort of optional)
00185     GattCharacteristic inputReportCharacteristic;
00186     GattCharacteristic outputReportCharacteristic;
00187     GattCharacteristic featureReportCharacteristic;
00188 
00189     // Required gatt characteristics: Report Map, Information, Control Point
00190     GattCharacteristic reportMapCharacteristic;
00191     ReadOnlyGattCharacteristic<HID_information_t> HIDInformationCharacteristic;
00192     GattCharacteristic HIDControlPointCharacteristic;
00193 
00194     Ticker reportTicker;
00195     uint32_t reportTickerDelay;
00196     bool reportTickerIsActive;
00197 };
00198 
00199 #endif /* !HID_SERVICE_BASE_H_ */
00200