00001 /** 00002 * \file 00003 * 00004 * \brief USB host driver for Human Interface Device (HID) mouse interface. 00005 * 00006 * Copyright (C) 2011-2015 Atmel Corporation. All rights reserved. 00007 * 00008 * \asf_license_start 00009 * 00010 * \page License 00011 * 00012 * Redistribution and use in source and binary forms, with or without 00013 * modification, are permitted provided that the following conditions are met: 00014 * 00015 * 1. Redistributions of source code must retain the above copyright notice, 00016 * this list of conditions and the following disclaimer. 00017 * 00018 * 2. Redistributions in binary form must reproduce the above copyright notice, 00019 * this list of conditions and the following disclaimer in the documentation 00020 * and/or other materials provided with the distribution. 00021 * 00022 * 3. The name of Atmel may not be used to endorse or promote products derived 00023 * from this software without specific prior written permission. 00024 * 00025 * 4. This software may only be redistributed and used in connection with an 00026 * Atmel microcontroller product. 00027 * 00028 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 00029 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00030 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 00031 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 00032 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00033 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 00034 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00035 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 00036 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 00037 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 00038 * POSSIBILITY OF SUCH DAMAGE. 00039 * 00040 * \asf_license_stop 00041 * 00042 */ 00043 /* 00044 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a> 00045 */ 00046 00047 #ifndef _UHI_HID_MOUSE_H_ 00048 #define _UHI_HID_MOUSE_H_ 00049 00050 #include "conf_usb_host.h" 00051 #include "HIDDescriptors.h" 00052 #include "uhi.h" 00053 00054 #ifdef __cplusplus 00055 extern "C" { 00056 #endif 00057 00058 /** 00059 * \ingroup uhi_hid_mouse_group 00060 * \defgroup uhi_hid_mouse_group_uhc Interface with USB Host Core (UHC) 00061 * 00062 * Define and functions required by UHC. 00063 * 00064 * @{ 00065 */ 00066 00067 //! Global define which contains standard UHI API for UHC 00068 //! It must be added in USB_HOST_UHI define from conf_usb_host.h file. 00069 #define UHI_HID_MOUSE { \ 00070 .install = uhi_hid_mouse_install, \ 00071 .enable = uhi_hid_mouse_enable, \ 00072 .uninstall = uhi_hid_mouse_uninstall, \ 00073 .sof_notify = NULL, \ 00074 } 00075 00076 /** 00077 * \name Functions required by UHC 00078 * @{ 00079 */ 00080 extern USBH_enum_status_t uhi_hid_mouse_install(USBH_device_t* dev); 00081 extern void uhi_hid_mouse_enable(USBH_device_t* dev); 00082 extern void uhi_hid_mouse_uninstall(USBH_device_t* dev); 00083 //@} 00084 //@} 00085 00086 /** 00087 * \ingroup uhi_group 00088 * \defgroup uhi_hid_mouse_group UHI for Human Interface Device Mouse Class 00089 * 00090 * Common APIs used by high level application to use this USB host class. 00091 * 00092 * This API requires only callback definitions in conf_usb_host.h file 00093 * through following defines: 00094 * - \code #define UHI_HID_MOUSE_CHANGE(dev,b_plug) 00095 #define UHI_HID_MOUSE_EVENT_BTN_LEFT(b_state) 00096 #define UHI_HID_MOUSE_EVENT_BTN_RIGHT(b_state) 00097 #define UHI_HID_MOUSE_EVENT_BTN_MIDDLE(b_state) 00098 #define UHI_HID_MOUSE_EVENT_MOUVE(x,y,scroll) \endcode 00099 * 00100 * See \ref uhi_hid_mouse_quickstart. 00101 * @{ 00102 */ 00103 //@} 00104 00105 00106 /** 00107 * \page uhi_hid_mouse_quickstart Quick start guide for USB host mouse module (UHI mouse) 00108 * 00109 * This is the quick start guide for the \ref uhi_hid_mouse_group 00110 * "USB host mouse module (UHI mouse)" with step-by-step instructions on 00111 * how to configure and use the modules in a selection of use cases. 00112 * 00113 * The use cases contain several code fragments. The code fragments in the 00114 * steps for setup can be copied into a custom initialization function, while 00115 * the steps for usage can be copied into, e.g., the main application function. 00116 * 00117 * \section uhi_hid_mouse_basic_use_case Basic use case 00118 * In this basic use case, the "USB Host HID Mouse (Single Class support)" module is used. 00119 * The "USB Host HID Mouse (Multiple Classes support)" module usage is described 00120 * in \ref uhi_hid_mouse_use_cases "Advanced use cases". 00121 * 00122 * \section uhi_hid_mouse_basic_use_case_setup Setup steps 00123 * \subsection uhi_hid_mouse_basic_use_case_setup_prereq Prerequisites 00124 * \copydetails USBH_basic_use_case_setup_prereq 00125 * \subsection uhi_hid_mouse_basic_use_case_setup_code Example code 00126 * \copydetails USBH_basic_use_case_setup_code 00127 * \subsection uhi_hid_mouse_basic_use_case_setup_flow Workflow 00128 * \copydetails USBH_basic_use_case_setup_flow 00129 * 00130 * \section uhi_hid_mouse_basic_use_case_usage Usage steps 00131 * 00132 * \subsection uhi_hid_mouse_basic_use_case_usage_code Example code 00133 * Content of conf_usb_host.h: 00134 * \code 00135 #define USB_HOST_UHI UHI_HID_MOUSE 00136 #define UHI_HID_MOUSE_CHANGE(dev, b_plug) my_callback_mouse_change(dev, b_plug) 00137 extern bool my_callback_mouse_change(USBH_device_t* dev, bool b_plug); 00138 #define UHI_HID_MOUSE_EVENT_BTN_LEFT(b_state) my_callback_event_btn_left(b_state) 00139 extern void my_callback_event_btn_left(bool b_state); 00140 #define UHI_HID_MOUSE_EVENT_BTN_RIGHT(b_state) my_callback_event_btn_right(b_state) 00141 extern void my_callback_event_btn_right(bool b_state); 00142 #define UHI_HID_MOUSE_EVENT_BTN_MIDDLE(b_state) my_callback_event_btn_middle(b_state) 00143 extern void my_callback_event_btn_middle(bool b_state); 00144 #define UHI_HID_MOUSE_EVENT_MOUVE(x, y, scroll) my_callback_event_mouse(x, y, scroll) 00145 extern void my_callback_event_mouse(int8_t x, int8_t y, int8_t scroll); 00146 #include "uhi_hid_mouse.h" // At the end of conf_usb_host.h file 00147 \endcode 00148 * 00149 * Add to application C-file: 00150 * \code 00151 bool my_callback_mouse_change(USBH_device_t* dev, bool b_plug) 00152 { 00153 if (b_plug) { 00154 my_display_on_mouse_icon(); 00155 } else { 00156 my_display_off_mouse_icon(); 00157 } 00158 } 00159 00160 void my_callback_event_btn_left(bool b_state) 00161 { 00162 if (b_state) { 00163 // Here mouse button left pressed 00164 } else { 00165 // Here mouse button left released 00166 } 00167 } 00168 00169 void my_callback_event_mouse(int8_t x, int8_t y, int8_t scroll) 00170 { 00171 if (!x) { 00172 // Here mouse are moved on axe X 00173 cursor_x += x; 00174 } 00175 if (!y) { 00176 // Here mouse are moved on axe Y 00177 cursor_y += y; 00178 } 00179 if (!scroll) { 00180 // Here mouse are moved the wheel 00181 wheel += scroll; 00182 } 00183 } 00184 \endcode 00185 * 00186 * \subsection uhi_hid_mouse_basic_use_case_setup_flow Workflow 00187 * -# Ensure that conf_usb_host.h is available and contains the following configuration 00188 * which is the USB host mouse configuration: 00189 * - \code #define USB_HOST_UHI UHI_HID_MOUSE \endcode 00190 * \note It defines the list of UHI supported by USB host. 00191 * - \code #define UHI_HID_MOUSE_CHANGE(dev, b_plug) my_callback_mouse_change(dev, b_plug) 00192 extern bool my_callback_mouse_change(USBH_device_t* dev, bool b_plug); \endcode 00193 * \note This callback is called when a USB device mouse is plugged or unplugged. 00194 * - \code #define UHI_HID_MOUSE_EVENT_BTN_LEFT(b_state) my_callback_event_btn_left(b_state) 00195 extern void my_callback_event_btn_left(bool b_state); 00196 #define UHI_HID_MOUSE_EVENT_BTN_RIGHT(b_state) my_callback_event_btn_right(b_state) 00197 extern void my_callback_event_btn_right(bool b_state); 00198 #define UHI_HID_MOUSE_EVENT_BTN_MIDDLE(b_state) my_callback_event_btn_middle(b_state) 00199 extern void my_callback_event_btn_middle(bool b_state); 00200 #define UHI_HID_MOUSE_EVENT_MOUVE(x, y, scroll) my_callback_event_mouse(x, y, scroll) 00201 extern void my_callback_event_mouse(int8_t x, int8_t y, int8_t scroll) \endcode 00202 * \note These callbacks are called when a USB device mouse event is received. 00203 * 00204 * \section uhi_hid_mouse_use_cases Advanced use cases 00205 * For more advanced use of the UHI HID mouse module, see the following use cases: 00206 * - \subpage USBH_use_case_1 00207 * - \subpage USBH_use_case_2 00208 * - \subpage USBH_use_case_3 00209 */ 00210 00211 00212 #ifdef __cplusplus 00213 } 00214 #endif 00215 #endif // _UHI_HID_MOUSE_H_