SAMV71 Xplained Ultra Software Package 1.5

uhi_hid_mouse.h

Go to the documentation of this file.
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_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines