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