SAMV71 Xplained Ultra Software Package 1.3

uhi_hid_mouse.h

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