USBMouse.h

00001 /*
00002  * Copyright (c) 2018-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef USBMOUSE_H
00019 #define USBMOUSE_H
00020 
00021 #include "USBHID.h"
00022 #include "PlatformMutex.h"
00023 
00024 #define REPORT_ID_MOUSE   2
00025 
00026 /* Common usage */
00027 
00028 enum MOUSE_BUTTON {
00029     MOUSE_LEFT = 1,
00030     MOUSE_RIGHT = 2,
00031     MOUSE_MIDDLE = 4,
00032 };
00033 
00034 /* X and Y limits */
00035 /* These values do not directly map to screen pixels */
00036 /* Zero may be interpreted as meaning 'no movement' */
00037 #define X_MIN_ABS    (1)        /*!< Minimum value on x-axis */
00038 #define Y_MIN_ABS    (1)        /*!< Minimum value on y-axis */
00039 #define X_MAX_ABS    (0x7fff)   /*!< Maximum value on x-axis */
00040 #define Y_MAX_ABS    (0x7fff)   /*!< Maximum value on y-axis */
00041 
00042 #define X_MIN_REL    (-127)     /*!< The maximum value that we can move to the left on the x-axis */
00043 #define Y_MIN_REL    (-127)     /*!< The maximum value that we can move up on the y-axis */
00044 #define X_MAX_REL    (127)      /*!< The maximum value that we can move to the right on the x-axis */
00045 #define Y_MAX_REL    (127)      /*!< The maximum value that we can move down on the y-axis */
00046 
00047 enum MOUSE_TYPE {
00048     ABS_MOUSE,
00049     REL_MOUSE,
00050 };
00051 
00052 /**
00053  * \defgroup drivers_USBMouse USBMouse class
00054  * \ingroup drivers-public-api-usb
00055  * @{
00056  */
00057 
00058 /**
00059  *
00060  * USBMouse example
00061  * @code
00062  * #include "mbed.h"
00063  * #include "USBMouse.h"
00064  *
00065  * USBMouse mouse;
00066  *
00067  * int main(void)
00068  * {
00069  *   while (1)
00070  *   {
00071  *      mouse.move(20, 0);
00072  *      wait(0.5);
00073  *   }
00074  * }
00075  *
00076  * @endcode
00077  *
00078  *
00079  * @code
00080  * #include "mbed.h"
00081  * #include "USBMouse.h"
00082  * #include <math.h>
00083  *
00084  * USBMouse mouse(true, ABS_MOUSE);
00085  *
00086  * int main(void)
00087  * {
00088  *   uint16_t x_center = (X_MAX_ABS - X_MIN_ABS)/2;
00089  *   uint16_t y_center = (Y_MAX_ABS - Y_MIN_ABS)/2;
00090  *   uint16_t x_screen = 0;
00091  *   uint16_t y_screen = 0;
00092  *
00093  *   uint32_t x_origin = x_center;
00094  *   uint32_t y_origin = y_center;
00095  *   uint32_t radius = 5000;
00096  *   uint32_t angle = 0;
00097  *
00098  *   while (1)
00099  *   {
00100  *       x_screen = x_origin + cos((double)angle*3.14/180.0)*radius;
00101  *       y_screen = y_origin + sin((double)angle*3.14/180.0)*radius;
00102  *
00103  *       mouse.move(x_screen, y_screen);
00104  *       angle += 3;
00105  *       wait(0.01);
00106  *   }
00107  * }
00108  *
00109  * @endcode
00110  *
00111  * @note Synchronization level: Thread safe
00112  */
00113 class USBMouse: public USBHID {
00114 public:
00115 
00116     /**
00117     * Basic constructor
00118     *
00119     * Construct this object optionally connecting and blocking until it is ready.
00120     *
00121     * @note Do not use this constructor in derived classes.
00122     *
00123     * @param connect_blocking true to perform a blocking connect, false to start in a disconnected state
00124     * @param mouse_type Mouse type: ABS_MOUSE (absolute mouse) or REL_MOUSE (relative mouse) (default: REL_MOUSE)
00125     * @param vendor_id Your vendor_id
00126     * @param product_id Your product_id
00127     * @param product_release Your product_release
00128     */
00129     USBMouse(bool connect_blocking = true, MOUSE_TYPE mouse_type = REL_MOUSE, uint16_t vendor_id = 0x1234, uint16_t product_id = 0x0001, uint16_t product_release = 0x0001);
00130 
00131     /**
00132     * Fully featured constructor
00133     *
00134     * Construct this object with the supplied USBPhy and parameters. The user
00135     * this object is responsible for calling connect() or init().
00136     *
00137     * @note Derived classes must use this constructor and call init() or
00138     * connect() themselves. Derived classes should also call deinit() in
00139     * their destructor. This ensures that no interrupts can occur when the
00140     * object is partially constructed or destroyed.
00141     *
00142     * @param phy USB phy to use
00143     * @param mouse_type Mouse type: ABS_MOUSE (absolute mouse) or REL_MOUSE (relative mouse) (default: REL_MOUSE)
00144     * @param vendor_id Your vendor_id
00145     * @param product_id Your product_id
00146     * @param product_release Your product_release
00147     */
00148     USBMouse(USBPhy *phy, MOUSE_TYPE mouse_type = REL_MOUSE, uint16_t vendor_id = 0x1234, uint16_t product_id = 0x0001, uint16_t product_release = 0x0001);
00149 
00150     /**
00151      * Destroy this object
00152      *
00153      * Any classes which inherit from this class must call deinit
00154      * before this destructor runs.
00155      */
00156     virtual ~USBMouse();
00157 
00158     /**
00159     * Write a state of the mouse
00160     *
00161     * @param x x-axis position
00162     * @param y y-axis position
00163     * @param buttons buttons state (first bit represents MOUSE_LEFT, second bit MOUSE_RIGHT and third bit MOUSE_MIDDLE)
00164     * @param z wheel state (>0 to scroll down, <0 to scroll up)
00165     * @returns true if there is no error, false otherwise
00166     */
00167     bool update(int16_t x, int16_t y, uint8_t buttons, int8_t z);
00168 
00169     /**
00170     * Move the cursor to (x, y)
00171     *
00172     * @param x x-axis position
00173     * @param y y-axis position
00174     * @returns true if there is no error, false otherwise
00175     */
00176     bool move(int16_t x, int16_t y);
00177 
00178     /**
00179     * Press one or several buttons
00180     *
00181     * @param button button state (ex: press(MOUSE_LEFT))
00182     * @returns true if there is no error, false otherwise
00183     */
00184     bool press(uint8_t button);
00185 
00186     /**
00187     * Release one or several buttons
00188     *
00189     * @param button button state (ex: release(MOUSE_LEFT))
00190     * @returns true if there is no error, false otherwise
00191     */
00192     bool release(uint8_t button);
00193 
00194     /**
00195     * Double click (MOUSE_LEFT)
00196     *
00197     * @returns true if there is no error, false otherwise
00198     */
00199     bool double_click();
00200 
00201     /**
00202     * Click
00203     *
00204     * @param button state of the buttons ( ex: clic(MOUSE_LEFT))
00205     * @returns true if there is no error, false otherwise
00206     */
00207     bool click(uint8_t button);
00208 
00209     /**
00210     * Scrolling
00211     *
00212     * @param z value of the wheel (>0 to go down, <0 to go up)
00213     * @returns true if there is no error, false otherwise
00214     */
00215     bool scroll(int8_t z);
00216 
00217     /*
00218     * To define the report descriptor. Warning: this method has to store the length of the report descriptor in reportLength.
00219     *
00220     * @returns pointer to the report descriptor
00221     */
00222     virtual const uint8_t *report_desc();
00223 
00224 protected:
00225     /*
00226     * Get configuration descriptor
00227     *
00228     * @returns pointer to the configuration descriptor
00229     */
00230     virtual const uint8_t *configuration_desc(uint8_t index);
00231 
00232 private:
00233     MOUSE_TYPE _mouse_type;
00234     uint8_t _button;
00235     uint8_t _configuration_descriptor[41];
00236     PlatformMutex _mutex;
00237 
00238     bool mouse_send(int8_t x, int8_t y, uint8_t buttons, int8_t z);
00239 };
00240 
00241 /** @}*/
00242 
00243 #endif