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 "USBHID_Types.h"
00024 
00025 #define BLE_UUID_DESCRIPTOR_REPORT_REFERENCE 0x2908
00026 #define BLE_UUID_DESCRIPTOR_EXTERNAL_REPORT_REFERENCE 0x2907
00027 
00028 typedef const uint8_t report_map_t[];
00029 typedef const uint8_t * report_t;
00030 
00031 typedef struct {
00032     uint16_t bcdHID;
00033     uint8_t  bCountryCode;
00034     uint8_t  flags;
00035 } HID_information_t;
00036 
00037 enum ReportType {
00038     INPUT_REPORT    = 0x1,
00039     OUTPUT_REPORT   = 0x2,
00040     FEATURE_REPORT  = 0x3,
00041 };
00042 
00043 enum ProtocolMode {
00044     BOOT_PROTOCOL   = 0x0,
00045     REPORT_PROTOCOL = 0x1,
00046 };
00047 
00048 typedef struct {
00049     uint8_t ID;
00050     uint8_t type;
00051 } report_reference_t;
00052 
00053 
00054 class HIDServiceBase {
00055 public:
00056     /**
00057      *  Constructor
00058      *
00059      *  @param _ble
00060      *         BLE object to add this service to
00061      *  @param reportMap
00062      *         Byte array representing the input/output report formats. In USB HID jargon, it
00063      *         is called "HID report descriptor".
00064      *  @param reportMapLength 
00065      *         Size of the reportMap array
00066      *  @param outputReportLength
00067      *         Maximum length of a sent report (up to 64 bytes) (default: 64 bytes)
00068      *  @param inputReportLength
00069      *         Maximum length of a received report (up to 64 bytes) (default: 64 bytes)
00070      */
00071     HIDServiceBase(
00072         BLE &_ble,
00073         report_map_t reportMap,
00074         uint8_t reportMapLength,
00075         report_t inputReport,
00076         report_t outputReport,
00077         report_t featureReport,
00078         uint8_t inputReportLength = 0,
00079         uint8_t outputReportLength = 0,
00080         uint8_t featureReportLength = 0
00081     );
00082 
00083     /**
00084      *  Send Report
00085      *
00086      *  @param report   Report to send. Must be of size @ref inputReportLength
00087      *  @return         The write status
00088      *
00089      *  @note Don't call send() directly for multiple reports! Use reportTicker for that, in order
00090      *  to avoid overloading the BLE stack, and let it handle events between each report.
00091      */
00092     virtual ble_error_t send(const report_t report);
00093 
00094     /**
00095      *  Read Report
00096      *
00097      *  @param report   Report to fill. Must be of size @ref outputReportLength
00098      *  @return         The read status
00099      */
00100     virtual ble_error_t read(report_t report);
00101 
00102     virtual void onConnection(const Gap::ConnectionCallbackParams_t *params);
00103     virtual void onDisconnection(const Gap::DisconnectionCallbackParams_t *params);
00104 
00105     virtual bool isConnected(void) {
00106         return connected;
00107     }
00108 
00109     virtual void init(void);
00110 
00111 protected:
00112     /**
00113      * Called by BLE API when data has been successfully sent.
00114      *
00115      * @param count     Number of reports sent
00116      *
00117      * @note Subclasses can override this to avoid starting the report ticker when there is nothing
00118      * to send
00119      */
00120     virtual void onDataSent(unsigned count);
00121 
00122     /**
00123     */
00124     virtual void onDataWritten(const GattWriteCallbackParams *params);
00125 
00126     virtual void addExtraCharacteristics(GattCharacteristic** characteristics, uint8_t& charIndex);
00127 
00128 protected:
00129     BLE &ble;
00130     bool connected;
00131 
00132     int reportMapLength;
00133 
00134     report_t inputReport;
00135     report_t outputReport;
00136     report_t featureReport;
00137 
00138     uint8_t inputReportLength;
00139     uint8_t outputReportLength;
00140     uint8_t featureReportLength;
00141 
00142     uint8_t controlPointCommand;
00143     uint8_t protocolMode;
00144 
00145     // Optional gatt characteristics:
00146     GattCharacteristic protocolModeCharacteristic;
00147 
00148     // Report characteristics (each sort of optional)
00149     GattCharacteristic inputReportCharacteristic;
00150     GattCharacteristic outputReportCharacteristic;
00151     GattCharacteristic featureReportCharacteristic;
00152 
00153     // Required gatt characteristics: Report Map, Information, Control Point
00154     GattCharacteristic reportMapCharacteristic;
00155     ReadOnlyGattCharacteristic<HID_information_t> HIDInformationCharacteristic;
00156     GattCharacteristic HIDControlPointCharacteristic;
00157 };
00158 
00159 #endif /* !HID_SERVICE_BASE_H_ */